AI Database Map

オープンデータ（乗降客数・人口・地価・バス・事業所・従業者）を 駅 × 半径 で集約し、地図 ＋ AI で誰でも使えるようにする、AIネイティブな Web アプリ。

鉄道会社の輸送計画、店舗出店の商圏分析、住宅購入の検討などを想定しています。

---

コンセプト：「API こそがプロダクト」

従来の SaaS は UI が特権的で API は副産物でした。本プロジェクトはこれを反転させ、人間の UI と AI（LLM）が同じ共通 API を対等に叩く構造にします。メトリクスの定義・ラベル・単位・半径変換・ランキング・クラスタリングといった「意味」は、すべてサーバの共通 API（＝ドメイン層）が持ちます。

flowchart TB
    LLM["LLM（アプリ内 Gemini／<br/>ユーザーの Claude・MCP クライアント）"]
    UI["構造化 UI<br/>Next.js / MapLibre"]
    API["共通 API（app/api）<br/>自己記述カタログ・Zod 検証・エラー封筒"]
    DOM["ドメインロジック（src/domain）<br/>不変条件・意味・単位・計算（framework 非依存）"]
    DB["Supabase<br/>PostgreSQL + PostGIS + RLS"]
    LLM --> API
    UI --> API
    API --> DOM
    DOM --> DB

• 自己記述的：利用可能な指標・半径・年・単位・ラベルを機械可読で返すメトリクス・カタログを単一の真実（src/shared/catalog）として持ち、UI・API・（将来の）AI ツールがすべてこれを参照します。
• 通信契約：フロントと AI が従う標準インターフェース「GUI Chat Protocol (Map Edition)」の型に API 応答を合致させ、クリックと会話が同じ描画パスを通るように設計しています。

---

主な機能（Step1）

• 全国 9,273 駅の地図（国土地理院ベクトルタイル・クラスタリング）
• 駅名検索 → 駅クリックで詳細パネル（乗降客・人口〔実績＋将来推計2系統〕・地価・バス・事業所・従業者のチャート＋信頼性フラグ）
• 半径切替（6段：500m〜20km） — 再フェッチなしで即時再計算
• 都道府県ランキング（複数県・全件ページング・低分母除外）
• 増減率の散布図（決定的 k-means クラスタリング）
• データ出典・ライセンス表示（カタログから自動生成）
• モバイル対応・エラー/オフライン/404 ハンドリング

---

あなたの Claude で使う（Step2・リモート MCP）

共通 API を**リモート MCP サーバ（15 ツール・読み取り専用・認証不要）**として公開しています。 ユーザー自身の Claude サブスクリプション（API キー不要・追加費用なし）で、住宅購入・鉄道の輸送計画・出店の商圏分析などの分析グレードの支援ができます。 導入ページ：https://ai-database-map.vercel.app/ai

導入

クライアント	手順
Claude Code（推奨・スキル込み）	/plugin marketplace add kusui26/AI-Database-Map → /plugin install ai-database-map@ai-database-map
Claude.ai（Free でも 1 個まで）	導入リンク、または 設定 › コネクタに URL を追加：https://ai-database-map.vercel.app/api/mcp（認証なし）
Claude Cowork	Connectors に同じ URL・Plugins に kusui26/AI-Database-Map（git URL）
Codex CLI	codex plugin marketplace add kusui26/AI-Database-Map → /plugins から Install（.codex-plugin／.agents 同梱）
ChatGPT / Cursor / VS Code など	同じ MCP URL（streamable HTTP）

入っているもの

• ツール 15 本：駅検索・一覧（市区町村/会社/路線/範囲）・build_dataset（駅×指標 CSV を短命 URL で 1 回生成・災害列の結合可）・render_map（結果を地図にした HTML ページを短命 URL で生成）・get_hazard_summary（全駅事前計算の災害サマリ ≤500 駅一括）・get_station_profile（駅周辺のプロフィール：要点と県内／市内での位置・性格の目安・見ていないこと）・get_area_summary（市区町村・都道府県・路線の沿線の全体：2025 年国勢調査までの公表値・将来推計・内訳・比較・駅の色分け）・駅詳細・ランキング・散布・地点ハザード・警報・避難場所・脱出方向・自己記述カタログ
• スキル（Claude Code / Cowork / Codex）：分析の型（station-analysis）＋用途別レシピ——住宅 /ai-database-map:recommend・輸送計画 :demand・出店 :market——＋ analyze-csv・hazard-reading。図を出せるホスト（MulmoTerminal / MulmoClaude の Canvas）では、要件をフォームで聞き、チャートと地図も出します（無い環境では従来どおりの表と文章）。MulmoClaude は 1.18.0 以上なら MCP の登録と地図タイルの CSP の 2 つだけで、スキルはプラグインのまま効きます（1.18.0 より前に必要だった回避策は上流の修正で不要になりました）——手順は プラグインの README
• golden 受け入れテスト：plugins/ai-database-map/evals/（claude plugin eval 形式・4 シナリオの実走で 14/14 合格済み——住宅 5/5・輸送計画 3/3・出店 3/3・母艦の Canvas 3/3）

プラン・利用枠の注意

• 推論はユーザーの枠を消費します（Pro/Max は 5 時間枠＋週次枠を Claude／Claude Code／Cowork で共有。寄与率は /usage）
• 枠にやさしい設計：応答は要約中心・多数駅の行データは CSV の URL で渡してローカルで分析（150 駅×20 指標でもツール呼び出しは数回）
• サーバ側レート制限あり（IP 60 回/分・生成系は厳しめ）。災害の応答は limitations（想定であり現況ではない等）を必ず同梱します

---

技術スタック

領域	採用
フレームワーク	Next.js 16（App Router・Turbopack）/ React 19 / TypeScript 6
スタイル	Tailwind CSS v4
地図	MapLibre GL JS（国土地理院 最適化ベクトルタイル）
チャート	Chart.js 4 + react-chartjs-2
状態	Zustand（地図・選択）+ nuqs（URL 同期）
データ取得	SWR
契約・検証	Zod 4（z.infer で型導出）
DB	Supabase（PostgreSQL + PostGIS + PostgREST RPC・RLS）
テスト/品質	Vitest 4 / ESLint 10（any・as 禁止＋レイヤ境界ルール）/ Prettier
データ生成	Python（pandas・psycopg）
デプロイ	Vercel（+ Cron による Supabase keep-alive）

---

セットアップ

前提

• Node.js 22.x / pnpm 11
• Supabase プロジェクト（PostgreSQL + PostGIS）
• （データ生成する場合のみ）Python 3・e-Stat API の appId

手順

# 1. 依存インストール
pnpm install

# 2. 環境変数（.env.example をコピーして実値を記入。.env は gitignore 済み）
cp .env.example .env
#   アプリ実行に最低限必要：SUPABASE_URL / SUPABASE_ANON_KEY
#   本番の OG/canonical 用：NEXT_PUBLIC_SITE_URL

# 3. 開発サーバ
pnpm dev            # http://localhost:3000

# 4. 品質ゲート
pnpm typecheck
pnpm lint
pnpm test

# 5. 本番ビルド / 起動
pnpm build
pnpm start

データパイプライン（任意・データを作り直す場合）

pipeline/ の Python スクリプトで、公開オープンデータ → ワイド CSV（data/derived/station_dataset.csv）→ カタログ（catalog.json）→ Supabase 投入（stations / metric_columns / station_values）を行います。data/ と slide/ は容量・機密のため gitignore です。

---

データ出典・ライセンス

このリポジトリのソースコードは MIT License です。データは MIT の対象外で、下の表と各出典の条件に従います。対象は、アプリが表示する統計・ハザード情報・地図タイルと、リポジトリ内の気象庁の区域表、condminium/OpenStreetMap_tokyo_sample.csv（© OpenStreetMap contributors・ODbL）です。

指標カタログ（src/shared/catalog/catalog.json）の各エントリが source / license を持ち、アプリ内の「このアプリ・データ出典」ダイアログに自動生成で表示されます。

出典	対象	ライセンス
国土数値情報「駅別乗降客数」(S12)	乗降客数	CC BY 4.0 相当（利用約款・出典明記で商用可）
総務省 国勢調査 地域メッシュ統計（e-Stat）	人口	CC BY 4.0（政府統計）
国土数値情報 将来推計人口メッシュ	将来推計人口	CC BY 4.0 相当
国土数値情報「地価公示」(L01)	地価	CC BY 4.0 相当
国土数値情報 バス停留所 P11 ＋ 高速バス P36	バス	CC BY 4.0
国土数値情報 バス停留所 P11（2010・増減率の分母）	バス	⚠ 非商用（商用は要確認）
経済センサス‑活動調査 地域メッシュ統計（e-Stat）	事業所・従業者	CC BY 4.0 相当

地図：国土地理院 最適化ベクトルタイル。数値は各公的統計の二次加工であり、原典の定義・年次・集計単位に依存します。

---

プロジェクト構成

src/
  app/            Next.js ルート（page / layout / api / error / not-found …）
  components/     UI（地図・ヘッダ・検索・FAB・ダイアログ・パネル）
  domain/         ドメインロジック（純関数・framework 非依存・DB 非依存）
  db/             Supabase クライアント＋RPC ラッパ（Zod 検証）
  shared/         カタログ・契約（api / protocol）・定数・整形
supabase/migrations/   バージョン管理された SQL（RPC・スキーマ・RLS）
pipeline/         データ生成・投入（Python）
docs/             設計ドキュメント（architecture.md / plan_fable.md ほか）
tests/            ドメイン純関数の単体テスト（Vitest）

依存方向は UI → 共通 API → domain → DB の一方向。ESLint のレイヤ境界ルールで domain から UI/DB への import を禁止しています。

---

デプロイ

Vercel に接続し、main へのマージで本番デプロイされます。vercel.json の Cron（毎日 03:00 UTC → /api/health）が DB に 1 クエリ投げます——本番から DB へ届くことの日次確認です（失敗を知らせる仕組みは用意していません。元は Supabase 無料枠の自動停止対策でしたが、Pro では不要になりました）。本番の環境変数（SUPABASE_URL / SUPABASE_ANON_KEY / NEXT_PUBLIC_SITE_URL）は Vercel ダッシュボードで設定します。

---

ドキュメント

• docs/architecture.md — アーキテクチャ・スキーマ・共通 API・デプロイ
• docs/plan_fable.md — 実装計画と進捗
• .claude/CLAUDE.md — 開発指針・コーディング規約

---

ステータス

Step1（データ刷新＋公開）・Step2（AI ネイティブ化）完了。 アプリ内 Gemini チャットに加え、リモート MCP（15 ツール）＋ Claude Code / Codex プラグイン＋分析スキル（3 ユースケースの golden 受け入れテストつき）を公開済み。経緯と設計判断は docs/260828_research_claude_auth.md（Step2 まで）と docs/260912_gui_chat_protocol.md（以降）を参照。