TanStack Start開発に向けたドキュメント検索基盤の構築ログ

🤔 TanStack Startで開発を始めたいが、情報源はどこにある？

TanStack Startを使って開発しようと思い立った。Next.jsやRemixの競合となるこのフレームワークは、「Type-Safe（型安全）」を最優先にしているらしい。エコシステム全体を理解する必要がありそうだ。

まずは必要なライブラリと、見るべきドキュメントを整理しよう。Startは単体で動くというより、TanStackファミリーの集合体のようなものだ。

Core (必須)

1. TanStack Start: フレームワーク本体。SSRやServer Functionsを提供する。
2. TanStack Router: これが土台。Startは実質「サーバー機能付きのRouter」と言える。
3. Vite: ビルドツール。

Standard Stack (推奨)

1. TanStack Query: 非同期データ管理。RouterのLoaderと統合されている。
2. TanStack Form: フォーム管理。型安全性が高く、Server Functionsとの相性が良い。
3. Zod: スキーマバリデーション。RouterのSearch Paramsの型定義に必須。

Backend / UI (推奨)

1. Drizzle ORM: DB操作。Prismaより軽量でTypeScriptとの親和性が高い。
2. Tailwind CSS: スタイリング。

学習順序としては、Routerの理解が最優先（8割を占める）。次にStartのサーバー機能、そしてQueryやFormといった周辺ライブラリという流れになるだろう。GitHubのExamplesを見るのが一番の近道かもしれない。

💡 ドキュメント検索用のMCPサーバーを作ろう

開発を進める上で、これらのドキュメントを行ったり来たりするのは大変だ。そこで、ドキュメント検索用のMCPサーバー[^1]を作って、効率的に情報を引き出せるようにしたい。

そのためには、まずクロール対象となるドキュメントのURLリストが必要だ。ReactやTypeScriptの基礎情報も含めて、網羅的なリストを作っておく。

[
  "https://react.dev/",
  "https://www.typescriptlang.org/docs/",
  "https://developer.mozilla.org/ja/docs/Web/API",
  "https://tanstack.com/start/latest/docs",
  "https://tanstack.com/router/latest/docs",
  "https://tanstack.com/query/latest/docs",
  "https://tanstack.com/form/latest/docs",
  "https://zod.dev/",
  "https://vite.dev/guide/",
  "https://vite.dev/config/"
]

MDNを含めたのは、StartのServer Functionsが標準Web API（Request/Response）に準拠しているからだ。Node.js固有のAPIではない点に注意が必要。

⚙️ 集合知による宣言的なスクレイピング設定

ドキュメントサイトごとにHTML構造は異なる。これを解析してMarkdownに変換するロジックを、Pythonスクリプトで個別に書くのはメンテナンスコストが高すぎる。

そこで、「ドキュメントの構造定義をJSON設定ファイルに外出しする」アプローチを取ることにする。これならGitHub上で設定ファイルを管理でき、サイト構造が変わってもJSONを修正するだけで済む。いわば「集合知」でメンテナンスするシステムだ。

chrome-devtools-mcp[^2] を使って、実際のサイト構造を解析し、このJSON設定ファイルを生成させよう。

必要なツールのインターフェースイメージ：

tools = [
  "search_document",  # 検索して該当ドキュメントのリストを返す
  "read_document",    # 指定されたドキュメントの中身をMarkdownで返す
  "recommend_docs"    # コンテキストに合わせて読むべきドキュメントを提案する
]

この設定ファイル生成のために、Claude Codeに渡すプロンプトを考える必要がある。

🧐 設定生成プロンプトの設計：ReadとSearchの分離

単純にURLを渡して「解析して」と言うだけでは不十分だ。read_document（抽出）と search_document（探索）では、必要な情報が異なる。

1. Read用（記事単体の抽出） 記事本文を綺麗に抜き出すための設定。

{
  "extraction": {
    "title": "h1.text-3xl",
    "content": "main article",
    "exclude": [".carbon-ads", "button[aria-label='Edit page']"]
  }
}

2. Search/Recommend用（サイト全体のナビゲーション） サイドバーや次のページへのリンクを解析する設定。

{
  "navigation": {
    "sidebar_items": "nav#sidebar ul li a",
    "pagination_next": "a.pagination-next"
  }
}

3. Pagination用（順次読み込み） ドキュメントを順番に学習させるために、「次の記事」への遷移ルールも必要だ。 Zodのような「1ページ完結型（Single Page）」と、TanStackのような「複数ページ型（Multi Page）」を識別する必要がある。

{
  "pagination": {
    "type": "linear_next_button",
    "next_link": "a.nav-next"
  }
}

これらを別々のプロンプトで解析させ、最終的に一つのJSON設定ファイルにマージするのが良さそうだ。

🚧 予測される困難とその対策：セレクタの脆弱性と「取りこぼし」

このアプローチにはいくつかの落とし穴がある。

1. セレクタの脆弱性 (Selector Fragility) Tailwind CSSなどのハッシュ付きクラス名は頻繁に変わる。 -> 対策: セレクタを配列で持ち、上から順に試す「フォールバック戦略」を採用する。

"title": [
  "h1.text-3xl",       // Specific (高精度だが壊れやすい)
  "article h1",        // Semantic (構造的)
  "h1"                 // Generic (最終手段)
]

2. SPA/CSR対応 単純なHTTP GETではコンテンツが空の場合がある。 -> 対策: Playwrightなどでブラウザレンダリング後のDOMを取得する。

3. 全文取得できないリスク フォールバック戦略の弱点として、誤って「記事の一部だけの要素」にマッチして終了してしまう可能性がある。 例えば、本当は main 全体が欲しいのに、冒頭の .intro だけ取得してしまうケース。

-> 対策A: 「引き算」のアプローチ content セレクタは、極力「大きな枠（main, article）」を狙う。その上で、exclude で広告やナビゲーションを削る。

-> 対策B: コンテンツ量によるバリデーション ヒットした要素の文字数が少なすぎる場合（例: 200文字以下）、それは「全文」ではないと判断し、次のセレクタを試行するロジックをMCPサーバー側に実装する。

最終的なJSON設定のイメージはこうなる。

{
  "domain": "tanstack.com",
  "extraction": {
    // 広い範囲（親）から順にではなく、信頼できる順に並べる
    // ただし、誤って部分要素を拾わないよう、実装側で文字数チェックを行う
    "content": [
      "div[class^='DocSearch-content']",
      "article",
      "main"
    ],
    "exclude": [
      ".carbon-ads",
      "button[aria-label='Edit this page']",
      "nav",
      "footer"
    ]
  },
  // ...navigation settings
}

よし、これで「集合知設定ファイル」をベースにした堅牢なドキュメント検索システムの設計ができた。まずは手始めにTanStack Routerのドキュメントから設定ファイルを生成してみよう。

[^1]: Model Context Protocol。AIモデルと外部ツール（データベース、API、ブラウザなど）を接続するための標準規格。
[^2]: ブラウザのDevToolsをMCP経由で操作できるようにするツール。これを使うことでAIが実際にウェブページにアクセスし、DOM構造を解析できる。