This is a Next.js project bootstrapped with create-next-app.

旅程管理ウェブアプリケーション「車旅のしおり」

概要

旅行計画の作成から実施までをサポートするウェブアプリケーションで、Google Maps 連携により効率的な旅程管理を実現します。カーナビゲーション（Android Auto・Apple CarPlay）との連携を前提に設計されており、旅行中の移動をスムーズにサポートします。

全国の車中泊スポット情報（トイレ・入浴施設、安全性、静けさなど）を地図で検索でき、気になるスポットは旅程に直接追加可能。ユーザー投稿機能により、コミュニティで情報を共有できます。

📱 Android アプリを Google Play で公開中: 車中泊スポットマップ｜車旅のしおり（アプリのソースは別リポジトリ tns-mobile で管理。詳細は後述の「モバイルアプリ（Android）」を参照）

主な機能

• 旅程作成・共有: 複数日にわたる旅行計画を簡単に作成。公開設定で他のユーザーと共有も可能です。車中泊スポットも簡単追加。
• 車中泊スポット情報: トイレ・入浴施設、コンビニまでの距離、安全性・静けさの情報を提供。車高（高さ制限）での絞り込みにも対応し、背の高い車でも入れるスポットを探せます。あなたのおすすめスポットも募集中！
• 地図連携: 各アクティビティに地図情報を紐づけて視覚的に管理。Google Maps から座標データ（例: 座標が埋め込まれた URL や、34.1560076,132.3973073）をクリップボード経由で簡単インポート。
• カーナビ連携: Android Auto・Apple CarPlay 対応。保存した位置情報から Google Maps を起動してルート検索。
• 簡単共有: 旅程を SNS（X・LINE・Facebook 等）やメールで簡単に共有できます。
• スポット投稿: あなたが見つけた車中泊スポットを投稿して、他の旅行者と情報を共有しましょう。
• AI で旅程の下書き: 出発地・目的地・泊数・好みから、実在の車中泊スポットを軸にした旅程の下書きを AI が生成（LLM API 活用）。現在は限定者のみの先行提供（ITINERARY_DRAFT_ALLOWED_EMAILS で指定）で、将来的にはプレミアム会員特典として提供予定です（プレミアム会員機能自体はまだ未提供）。詳細は ADR-0008 / ADR-0009 を参照。

モバイルアプリ（Android）

車中泊スポットを地図で手軽に探せる Android アプリ 「車中泊スポットマップ｜車旅のしおり」 を Google Play で公開しています。

• ストア: Google Play で見る（パッケージ名: club.over40web.tabi.spots）
• ソースコード: 本リポジトリ（tns-web）とは別リポジトリ tns-mobile で管理（Expo / React Native）。
• Web との関係: モバイルアプリは本 Web アプリが提供するモバイル向け公開 API（/api/v1/*）を利用して車中泊スポット情報を取得します。API は固定 API キーで保護されており、アプリ側は EXPO_PUBLIC_SPOTS_API_KEY、Web 側は SPOTS_API_KEY に同じ値を設定します（「モバイルアプリ向け API」の項および ADR-0006 を参照）。
• 位置づけ: 段階的なモバイル展開方針のもと、まずは車中泊スポット閲覧を軸にした Android アプリから提供しています。より高度な旅程管理は当面 Web アプリが主体です。

使用例

1. 旅行前: 複数日程の旅程を作成し、各スポットの位置情報を登録
2. 旅行中: 登録したスポットへのナビゲーションをワンタップで起動
3. 旅行後: 思い出の旅程を SNS で共有

Google Maps とシームレスに連携することで、旅行計画から実際の移動までをスムーズにサポートします。

技術的なハイライト

個人開発ながら実際のユーザーがいる本番サービスとして運用しており、思いつきではなく計測・比較検討に基づいて設計判断を行っています。主な判断は ADR（Architecture Decision Record） として記録しています。

アーキテクチャ

%%{init: {'theme':'neutral'}}%%
flowchart LR
    U["利用者 / Android アプリ"] --> CF["Cloudflare<br/>(プロキシ・キャッシュ・WAF)"]
    CF --> T["Cloudflare Tunnel"]
    T --> D["ConoHa VPS の Docker<br/>Next.js standalone"]
    D --> M["MongoDB Atlas"]
    D --> A["Auth0 (認証)"]
    D --> MB["Mapbox (地図・ジオコーディング)"]
    D --> LLM["Anthropic API<br/>(AI旅程ドラフト生成)"]
    D -.-> S["Sentry (エラー監視)"]
    D -.-> P["PostHog (アクセス解析)"]

1. AI旅程ドラフト生成（検索拡張生成 + 決定的検証）

出発地・目的地・泊数から旅程ドラフトを LLM で生成する機能。「実在しない場所をでっち上げる」という LLM 特有のリスクを、検索と検証をコード側に寄せることで抑えています。

• 検索（Retrieval）: 経路上の各泊地ごとに、MongoDB の地理空間クエリ（$geoWithin）で実在する車中泊スポットを検索し、ユーザーの好み（ペルソナ）や車両制約でスコアリング・絞り込み。
• 生成（Generation）: 検索結果のみを候補としてプロンプトに注入し、LLM は候補IDの中からしか選べない制約の下で構造化出力（Tool Use）として旅程を生成。
• 検証: 座標・候補ID・Zod スキーマの三重チェックで、LLM の出力を信頼せず機械的に検証（違反時は1回だけ再試行）。
• コスト管理: LLM 呼び出しは原子的な残高予約（$inc）で二重実行を防止し、成功時のみ消費する「ポイント制」で従量コストを制御。

詳細設計は ADR-0008（アーキテクチャ）・ADR-0009（コスト・アクセス制御）・ADR-0010（ポイント制）を参照。

2. インフラの意思決定: Vercel からセルフホスト VPS への移行

無料枠（Vercel Hobby）の CPU 使用量が利用増加に伴い恒常的に超過するようになったため、複数の移行先を比較検討した上で ConoHa VPS + Cloudflare Tunnel 構成へ移行（2026-09-20）。

検討した選択肢	見送った理由
Cloudflare Workers	PoC で Mongoose の共有接続が並列アクセス時に不安定。データアクセス層の書き換えが必須かつ Worker サイズが無料枠を超過
Netlify	試験デプロイで日本からの応答速度が実用上厳しく、リージョン選択には有料プランが必要
自宅ミニPC	セルフホスト自体は検証済みだが、初期費用とVPSとの損益分岐が約4年後。停電・回線障害・セキュリティリスクを自宅で負うことになる
Vercel Pro	運用の手間は最小だが、利用量に応じた課金で収支を予測しづらい（広告収入主体の小規模サービスのため）

移行前にアプリ側の CPU 削減（詳細ページの ISR 化、トップページのクエリキャッシュ、地図操作時の不要な RSC リクエスト削減）にも取り組んでおり、インフラ変更の前にアプリ側でできることを尽くす判断をしています。DNS の切り替えのみで Vercel へ即時ロールバックできる構成にして移行リスクを抑えました。詳細は docs/self-hosting/migration-plan.md を参照。

3. パフォーマンス最適化

• 旅程詳細ページに IndexedDB キャッシュを導入し、2回目以降の表示を約2秒 → 約200msに短縮。updatedAt の比較で古いキャッシュを検出する stale-while-revalidate 方式（src/lib/itineraryCache.ts）。
• React Compiler による自動メモ化。

4. セキュリティ: CSP の段階的ロールアウト

Content-Security-Policy は、広告（AdSense）や地図などサードパーティ接続先が多く「最初から全ブロック」では本番が壊れるリスクが高いため、段階的に適用しています。

• まず Content-Security-Policy-Report-Only で本番稼働させ、違反レポートを Sentry に集約して観測。
• 「壊すものがなく実害もゼロ」と確認できたディレクティブ（base-uri / object-src / frame-ancestors / form-action）だけを Content-Security-Policy（ブロック）として先行適用。ブラウザは複数の CSP ヘッダーを独立に評価するため、実運用への影響なく段階適用が成立します。
• 広告関連の違反が収束するごとに、ブロック側へディレクティブを移していく運用。

5. データ整合性

本番環境では Mongoose の autoIndex を無効化しています（サーバーレス的なコールドスタートのたびに索引同期が走るのを避けるため）。そのため索引追加はコードの schema.index() だけでは本番に反映されず、専用スクリプト（scripts/sync-indexes.cjs）でドライラン確認後に明示的に同期する運用にしています。ユニーク制約は索引だけに頼らずアプリケーション層でも重複チェックを行い、索引未作成環境でも制約が機能するようにしています。

主要技術

フレームワーク

• Next.js - React ベースのフルスタックフレームワーク

UI/UX ライブラリ

• React - ユーザーインターフェース構築用ライブラリ
• shadcn/ui - Radix UI と Tailwind CSS をベースにしたアクセシブルな UI コンポーネント
• Tailwind CSS - ユーティリティファーストの CSS フレームワーク (v4)
• Lucide React - アイコンライブラリ
• next-themes - ダークモード／テーマ切り替え
• Sonner - トースト通知
• canvas-confetti - 紙吹雪などの演出エフェクト

ドラッグ&ドロップ

• dnd kit - アクティビティの並べ替えに使用するドラッグ&ドロップツールキット

PWA / パフォーマンス

• @ducanh2912/next-pwa - Next.js 向け PWA 対応（オフライン・インストール促進）
• idb - IndexedDB のラッパー（詳細ページのキャッシュによる高速化）
• React Compiler - 自動メモ化によるレンダリング最適化

地図関連

• Mapbox GL - インタラクティブな地図実装
• React Leaflet - React 用地図コンポーネント

データ処理

• MongoDB - NoSQL データベース
• Mongoose - MongoDB のオブジェクトモデリングツール

状態管理

• Jotai - プリミティブで柔軟な React 向け状態管理ライブラリ

フォーム処理/バリデーション

• React Hook Form - フォーム状態管理
• Zod - TypeScript ファーストのスキーマバリデーション

認証

• @auth0/nextjs-auth0 - Auth0 による認証機能

メール送信

• Resend - トランザクショナルメール送信サービス

モニタリング・分析

• Sentry - エラー追跡と監視
• PostHog - プロダクト分析（トラフィック・機能利用・ファネル/定着）

開発ツール

• 言語: TypeScript
• リンター: ESLint
• フォーマッター: Prettier
• 環境変数: dotenv

.env.local の設定

Auth0

• AUTH0_SECRET:
  • Auth0 SDK が使用する秘密鍵。セッションの暗号化などに使用される。
• APP_BASE_URL:
  • アプリケーションのベース URL。ログイン後のリダイレクト先として使用される。
• AUTH0_CLIENT_ID:
  • Auth0 アプリケーションの識別子。認証リクエストに使用される。
• AUTH0_CLIENT_SECRET:
  • Auth0 アプリケーションの秘密鍵。トークン取得時などに使用される。
• AUTH0_DOMAIN:
  • Auth0 テナントのドメイン。認証エンドポイントの構築に使用される。
  • 例: your-tenant.auth0.com
  • 実行時に Auth0 SDK が参照するため必須。加えて next.config.mjs がビルド時にも参照し、CSP の form-action / connect-src に許可するオリジンを組み立てる（ビルド時に読めなかった場合に備えて同ファイルに既定値あり）。
• AUTH0_SCOPE:
  • アプリケーションが要求する権限（スコープ）を指定する。複数のスコープはスペースで区切る。
  • 例：openid profile email read:shows
• AUTH0_M2M_CLIENT_ID:
  • Auth0 Management API にアクセスするための Machine to Machine Application のクライアント ID。
  • ユーザー統計取得などの管理機能で使用される。
• AUTH0_M2M_CLIENT_SECRET:
  • Auth0 Management API にアクセスするための Machine to Machine Application のクライアント秘密鍵。
  • ユーザー統計取得などの管理機能で使用される。
• AUTH0_WEBHOOK_SECRET:
  • ユーザー登録通知の webhook（/api/auth/user-registered）を検証する共有シークレット。
  • Auth0 の Action 側で、同じ値を Authorization: Bearer <secret> ヘッダーに付けて送る。
  • 未設定の場合、webhook は 503 で拒否される（fail-closed。設定漏れで検証が無効化されるのを防ぐ）。

地図

• NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN:
  • Mapbox API にアクセスするためのトークン。地図の表示や機能の利用に必要（ブラウザ側で使用）。
• MAPBOX_SERVER_TOKEN（任意・AI旅程ドラフト生成を使う場合は推奨）:
  • サーバー側のジオコーディング（AI旅程ドラフト生成で観光地名→座標を解決）に使うトークン。
  • URL 制限なしのトークンを指定すること。URL 制限付きの NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN はサーバーからのリクエスト（Origin/Referer なし）が 403 になるため。
  • 未設定時は NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN にフォールバックするが、URL 制限があると 403 で座標解決に失敗しうる。
  • 例: pk.xxxxxxxx...

データベース

• MONGODB_URI:
  • MongoDB データベースに接続するための接続文字列。
  • 重要: データベース名を必ず含めてください（/データベース名?の形式）
  • 開発環境の例: mongodb+srv://username:[email protected]/itinerary_db_dev?retryWrites=true&w=majority
  • 本番環境の例: mongodb+srv://username:[email protected]/itinerary_db?retryWrites=true&w=majority
• APP_MONGODB_URI（開発環境のみ）:
  • 開発環境専用。Claude Code の MCP サーバー（mongodb-readonly）が MONGODB_URI を上書きする場合の回避策。
  • 設定されている場合、MONGODB_URI より優先して使用されます。
  • 本番環境（Vercel 等）では設定不要です。

環境別のデータベース設定:

• 開発環境 (.env.local): itinerary_db_dev を使用。MCP サーバーとの競合を避けるため APP_MONGODB_URI も設定を推奨。
• 本番環境 (Vercel 等の環境変数): itinerary_db を使用。MONGODB_URI のみで OK。
• 詳細は ENVIRONMENT_SETUP.md を参照してください。

モバイルアプリ向け API

• SPOTS_API_KEY（必須）:
  • /api/v1/*（モバイルアプリ向け公開API）を保護する固定APIキー。src/proxy.ts で検証される。
  • リクエストヘッダー x-api-key が一致しない場合に 401 を返す。未設定の環境では /api/v1/* は全て 401（fail-closed。設定漏れで保護が静かに無効化されるのを防ぐ）。
  • モバイルアプリ側は EXPO_PUBLIC_SPOTS_API_KEY に同じ値を設定する（tns-mobile リポジトリ参照）。
  • キーをローテーションすると旧バージョンのアプリは 401 になる点に注意（詳細は ADR-0006 追記）。
  • /api/v1/spots は Cache-Control: s-maxage=3600 を返しており、最大1時間 CDN にキャッシュされる。 そのためスポットの投稿・更新がアプリに反映されるまで最大1時間かかる場合がある。 セルフホスト環境（VPS + Cloudflare Tunnel）では、Cloudflare の WAF カスタムルールがエッジでキーを検証してから Cache Rules がキャッシュする構成になっており、鍵検証とキャッシュを両立している（詳細は docs/self-hosting/migration-plan.md を参照）。

実行環境

• APP_ENV（Vercel 以外で必須）:
  • 実行環境の名前（production / staging など）。Sentry の有効化と、CSP のレポート環境名の判定に使う（src/lib/appEnv.ts）。
  • Vercel では VERCEL_ENV が自動で設定されるため不要。セルフホスト（VPS の Docker）では VERCEL_ENV が空になるので、 本番では APP_ENV=production を設定しないと、サーバー側のエラーが Sentry に届かない。
  • next.config.mjs はビルド時にしか評価されないため、ビルド時にも渡す必要がある（scripts/deploy-vps.sh が build args で渡す）。

モニタリング・分析

• SENTRY_AUTH_TOKEN:
  • Sentry のビルド時認証トークン。ソースマップのアップロードなどに使用される。
• NEXT_PUBLIC_POSTHOG_KEY:
  • PostHog の Project API Key。アクセス解析（トラフィック・機能利用・ファネル/定着）に使用される。
  • 本番環境でのみ初期化される（開発環境では計測しない）。
  • 例: phc_XXXXXXXXXXXXXXXX
• NEXT_PUBLIC_POSTHOG_HOST:
  • PostHog のイベント送信先ホスト。未設定時は https://us.i.posthog.com。
  • EU リージョンの場合は https://eu.i.posthog.com。
• POSTHOG_PERSONAL_API_KEY / POSTHOG_PROJECT_ID / POSTHOG_API_HOST（任意）:
  • 退会（アカウント削除）時に PostHog の person を削除するためのサーバー用設定。
  • 未設定の場合、person 削除はスキップされる（退会処理自体は成功する）。
  • POSTHOG_API_HOST の既定は https://us.posthog.com（EU は https://eu.posthog.com）。

広告

• NEXT_PUBLIC_ADS_ENABLED:
  • 広告の共通スイッチ。未設定または false で停止（既定）。true で再開。
  • 停止中は AdSense スクリプト、上部広告（nafuda バナーを含む）、詳細ページの広告枠、開発用プレースホルダー、地図・一覧・詳細の広告リンク（ポータブル電源セール等）を表示しません。
  • 広告リンクは共通スイッチと NEXT_PUBLIC_SHOW_AD_LINK の両方が true の場合だけ表示します。
  • 広告ID・スロット設定は削除不要です。再開は既存設定を残したまま true に変更し、再ビルド・デプロイしてください。
  • 本番の停止にも、この変更をデプロイする必要があります。既に開いているページやオフラインキャッシュは更新されるまで旧表示が残る場合があります。
• NEXT_PUBLIC_ADSENSE_CLIENT_ID:
  • Google AdSense のクライアント ID。広告の表示に使用される。
  • 例: ca-pub-XXXXXXXXXXXXXXXX
• NEXT_PUBLIC_ADSENSE_SLOT_DETAIL_TOP / NEXT_PUBLIC_ADSENSE_SLOT_DETAIL_BOTTOM:
  • 車中泊スポット詳細ページの、上部・下部の広告枠 ID（AdSense の広告ユニット）。
  • 未設定の場合、その枠は表示されない。
  • 例: 1234567890

管理者

• ADMIN_EMAIL:
  • お問い合わせフォームの送信先となる管理者のメールアドレス。
  • 例: [email protected]
• ADMIN_EMAILS:
  • 管理者のメールアドレス一覧（サーバーサイド用）。カンマ区切りで複数指定可能。
  • 例: [email protected],[email protected]

AI旅程ドラフト生成

「AIで下書き」機能（実在の車中泊スポットを軸に旅程ドラフトを生成する機能）で使用する。設計の詳細は docs/adr/0008-itinerary-draft-generation-architecture.md および docs/adr/0009-ai-generation-cost-and-access-policy.md を参照。

• ANTHROPIC_API_KEY（この機能を使う場合は必須）:
  • Anthropic API のキー。旅程ドラフト生成の LLM 呼び出しに使用（モデルは claude-haiku-4-5、1 回あたり約 1〜2 円）。
  • console.anthropic.com → Settings → API Keys で発行。事前にクレジット購入が必要。git 追跡ファイルには実値を書かない。
  • 例: sk-ant-xxxxxxxx...
• ITINERARY_DRAFT_ALLOWED_EMAILS（この機能を使う場合は必須）:
  • AI 旅程ドラフト生成を利用できる「限定者」のメールアドレス一覧（サーバーサイド用・カンマ区切り）。ADMIN_EMAILS とは別枠の管理。
  • 未設定の場合、管理者を含め誰もこの機能を利用できない（ADR-0009 の「初版は限定者のみ」方針）。
  • 例: [email protected],[email protected]
• ジオコーディングには MAPBOX_SERVER_TOKEN（「地図」の項を参照）も使用する。

メール送信（Resend）

• RESEND_API_KEY:
  • Resend の API キー。お問い合わせフォームやシステム通知メールの送信に使用。
  • Resend → API Keys → Create API Key で発行（Permission = Sending access、Domain = over40web.club に限定）。
  • 例: re_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
• RESEND_FROM_EMAIL:
  • メール送信時の送信者メールアドレス。Resend で検証済みの over40web.club ドメインのアドレスを指定。
  • 例: [email protected]
• RESEND_FROM_NAME:
  • メール送信時の送信者名。
  • 例: 車旅のしおり

お問い合わせメールの転送フロー

お問い合わせフォームから送信されたメールは以下の流れで処理されます：

1. ユーザー送信 → お問い合わせフォーム入力・送信
2. Resend 経由 → [email protected] から送信
3. ドメイン転送 → Squarespace で設定されたメール転送（over40web.clubドメイン）
4. 管理者受信 → [email protected] に転送

メール転送設定の管理:

• ドメインのメール転送は Squarespace Domains で設定・管理
• [email protected] → [email protected] の転送設定

この設定により、お問い合わせ内容が確実に管理者チームに届きます。

Docker で動かす場合

$ docker-compose up --build

Getting Started

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Inter, a custom Google Font.

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.

ファイルの解説

• components.json
  • shadcn/ui ライブラリを使用する Next.js プロジェクトの設定ファイル
• sentry.*.ts
  • Sentry を Next.js アプリケーションに統合するための設定ファイル
    • sentry.client.config.ts:このファイルはクライアントサイド（ブラウザ）での Sentry の設定を行う。
    • ユーザーのブラウザで発生したエラーやパフォーマンスの問題を捕捉する。
    • sentry.edge.config.ts
      • このファイルは Edge 環境（例：Vercel Edge Functions）での Sentry の設定を行う。
      • サーバーレス関数やエッジコンピューティング環境で発生したエラーを追跡する。
    • sentry.server.config.ts:
      • このファイルはサーバーサイドでの Sentry の設定を行う。
      • Node.js 環境で実行されるサーバーサイドのコードで発生したエラーを捕捉する。

MongoDB MCP Server セットアップガイド

Claude Code で MongoDB Atlas データベースを安全に探索・分析するためのセットアップ手順

概要

Model Context Protocol (MCP) を使用して、Claude Code から MongoDB Atlas データベースに読み取り専用でアクセスできるようにする設定方法です。これにより、自然言語でデータベースの探索、スキーマ分析、データ分析が可能になります。

前提条件

• MongoDB Atlas アカウントとクラスター
• Node.js バージョン 20.19.0 以降
• Claude Code がインストール済み

セットアップ手順

1. MongoDB Atlas での読み取り専用ユーザー作成

1. MongoDB Atlas 管理画面にログイン
2. Security → Database Access に移動
3. Add New Database User をクリック
4. 以下の設定でユーザーを作成：

   Authentication Method: Password
   Username: claude_readonly
   Password: 強力なパスワード（保存しておく）
   Database User Privileges: Only read any database
   

2. ネットワークアクセスの設定

1. Security → Network Access に移動
2. 現在の IP アドレスまたは0.0.0.0/0（開発用）を追加

3. 接続文字列の確認

1. Database → Connect → Connect your application
2. 接続文字列をコピー：

   mongodb+srv://claude_readonly:[email protected]/?retryWrites=true&w=majority&appName=ClaudeMCP
   

4. 環境変数の設定

機密情報を安全に管理するため、接続文字列を環境変数で設定します。

.env.mcp ファイルの作成

# プロジェクトルートに .env.mcp ファイルを作成
echo "MONGODB_URI_READONLY=mongodb+srv://claude_readonly:[email protected]/?appName=ClaudeMCP" > .env.mcp

.gitignore への追加

# .gitignore に機密情報ファイルを追加
echo ".env.mcp" >> .gitignore
echo "setting.local.json" >> .gitignore

5. Claude Code MCP サーバーの追加

方法 A: 環境変数ファイルを使用（推奨）

# プロジェクトルートディレクトリで実行
claude mcp add -s project mongodb-readonly \
  --env-file .env.mcp \
  -e MDB_MCP_READ_ONLY="true" \
  -- npx -y @mongodb-js/mongodb-mcp-server --readOnly

方法 B: 直接指定（開発時のみ）

# 機密情報を直接指定（本番環境では非推奨）
claude mcp add -s project mongodb-readonly \
  -e MDB_MCP_CONNECTION_STRING="mongodb+srv://claude_readonly:[email protected]/?appName=ClaudeMCP" \
  -e MDB_MCP_READ_ONLY="true" \
  -- npx -y @mongodb-js/mongodb-mcp-server --readOnly

6. 接続確認

# MCP サーバー一覧を確認
claude mcp list

# 出力例：
# mongodb-readonly: npx -y @mongodb-js/mongodb-mcp-server - ✓ Connected

使用方法

Claude Code の起動

claude

MCP 接続状況の確認

/mcp

基本的なデータベース操作

データベース一覧の表示

データベース一覧を表示して

コレクション一覧の表示

itinerary_dbデータベースのコレクション一覧を教えて

スキーマ分析

itinerariesコレクションのフィールド一覧と各フィールドのデータ型を教えて

データ統計

itinerariesコレクションに何件のドキュメントがありますか？

サンプルデータの確認

itinerariesコレクションのサンプルデータを3件表示して

プロジェクト例：旅行計画アプリ

データベース構造

• データベース: itinerary_db
• コレクション: itineraries (4 件のドキュメント)

スキーマ詳細

フィールド	データ型	説明
_id	ObjectId	MongoDB 標準 ID
createdAt	String/Date	作成日時
dayPlans	Array	日別プラン
description	String	旅行の説明
isPublic	Boolean	公開設定
numberOfDays	Number	旅行日数
owner	Document	作成者情報
sharedWith	Array	共有ユーザー
startDate	String	開始日
title	String	旅行タイトル
updatedAt	Date	更新日時

高度な活用例

データ分析クエリ

「最も人気のある旅行先を分析して」
「過去1ヶ月の新規作成された旅行プラン数は？」
「平均的な旅行日数を教えて」

開発支援

「このスキーマに基づいてTypeScript型定義を生成して」
「Next.jsでitinerariesを取得するAPIルートのコードを書いて」
「MongoDB Aggregationパイプラインで人気の旅行先TOP5を取得するクエリを作成して」

コード生成

「MongooseスキーマでItineraryモデルを定義して」
「React コンポーネントでitinerary一覧を表示するコードを書いて」

トラブルシューティング

接続エラーの場合

1. ユーザー権限の確認

   • MongoDB Atlas で読み取り権限が設定されているか確認

2. ネットワークアクセス

   • IP アドレスが Atlas のアクセスリストに含まれているか確認

3. 接続文字列

   • パスワードに特殊文字が含まれる場合は URL エンコードが必要

MCP サーバーのリセット

# サーバーを削除
claude mcp remove mongodb-readonly

# 再度追加
claude mcp add -s project mongodb-readonly \
  -e MDB_MCP_CONNECTION_STRING="your-connection-string" \
  -e MDB_MCP_READ_ONLY="true" \
  -- npx -y @mongodb-js/mongodb-mcp-server --readOnly

セキュリティとファイル管理

Git 管理の設定

コミットするファイル

• ✅ .mcp.json - チーム共有の MCP 設定（機密情報なし）
• ✅ README.md - セットアップ手順

コミットしないファイル (.gitignore)

# MCP関連の機密情報
.env.mcp
setting.local.json

# Next.js環境変数
.env.local
.env.*.local

# その他
node_modules/
.next/

環境変数の管理

Next.js アプリ用

# .env.local（開発環境）
# APP_MONGODB_URI: MCP サーバーとの競合回避のため設定（開発環境のみ）
APP_MONGODB_URI=mongodb+srv://app_user:[email protected]/itinerary_db_dev
MONGODB_URI=mongodb+srv://app_user:[email protected]/itinerary_db_dev

# 本番環境（Vercel等）では MONGODB_URI のみ設定すれば OK
# MONGODB_URI=mongodb+srv://app_user:[email protected]/itinerary_db

Claude MCP 用

# .env.mcp
MONGODB_URI_READONLY=mongodb+srv://claude_readonly:[email protected]/?appName=ClaudeMCP

セキュアな.mcp.json 設定

チーム共有用の設定（機密情報を環境変数で参照）：

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    },
    "Sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "mongodb-readonly": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@mongodb-js/mongodb-mcp-server"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "${MONGODB_URI}",
        "MDB_MCP_READ_ONLY": "true"
      }
    }
  }
}

注意: 上記は Windows 環境用の設定です。

セキュリティ注意事項

• ✅ 読み取り専用ユーザーを使用
• ✅ 専用パスワードを設定
• ✅ IP アクセス制限を適用（本番環境）
• ✅ 環境変数で機密情報を管理
• ✅ 機密情報は Git コミットしない
• ❌ 本番データベースでの書き込み権限は付与しない

設定ファイル

.mcp.json（コミットする）

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    },
    "Sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "mongodb-readonly": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@mongodb-js/mongodb-mcp-server"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "${MONGODB_URI}",
        "MDB_MCP_READ_ONLY": "true"
      }
    },
    "context7-project": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}",
        "X-Project-Context": "travel-itinerary-nextjs"
      }
    }
  }
}

注意: Windows 環境では cmd /c npx の形式でコマンドを実行する必要があります。macOS/Linux では "command": "npx" と "args": ["-y", "@mongodb-js/mongodb-mcp-server"] の形式で設定してください。

.env.mcp（.gitignore に追加）

# Claude Code MCP用の読み取り専用接続文字列
MONGODB_URI_READONLY=mongodb+srv://claude_readonly:[email protected]/?appName=ClaudeMCP

MCP サーバー連携

Next.js DevTools

Next.js DevTools MCP サーバーを使用すると、Claude Code から Next.js アプリケーションの内部情報（ルート一覧、設定、ビルド情報など）に直接アクセスできます。

機能

• ルート一覧の取得: App Router / Pages Router のルート構造を確認
• エラー検出: ビルドエラー・ランタイムエラー・型エラーをリアルタイムで取得
• ページメタデータ: ルート・コンポーネント・レンダリング情報を参照
• Server Actionsの検査: Server ActionのIDからソースファイルと関数名を特定
• 開発ログの取得: ブラウザコンソールとサーバーログへのアクセス

設定

.mcp.json に以下の設定が含まれています：

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

注意: type を省略した場合は stdio として扱われます。

参考リンク

• Next.js MCP Getting Started

Sentry

Sentry MCP サーバーを使用すると、Claude Code から Sentry のエラー監視データに直接アクセスできます。

機能

• エラー検索: 自然言語でエラーを検索
• 問題詳細の取得: Issue ID から詳細情報とスタックトレースを取得
• Root Cause 分析: Seer AI によるエラーの根本原因分析
• 問題の更新: Issue のステータス変更やアサイン

設定

.mcp.json に以下の設定が含まれています：

{
  "mcpServers": {
    "Sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

認証

初回使用時に Sentry アカウントでの認証が必要です：

# Claude Code を起動
claude

# MCP 接続状況を確認
/mcp
# → "Authentication successful. Connected to Sentry." と表示されれば OK

使用例

# 本日のエラーを検索
「本日発生したエラーを表示して」

# 特定の Issue の詳細を取得
「TABI-NO-SHIORI-56 の詳細を教えて」

# 根本原因の分析
「この Issue の Root Cause 分析をして」

Context7

Context7 は AI アシスタント向けのコンテキスト管理サービスです。Claude Code との統合により、プロジェクトの履歴管理や高度なコンテキスト検索機能を提供します。

このプロジェクトでは、使用している技術スタック（Next.js 16、React 19、Tailwind CSS、Jotai、MongoDB、Auth0 など）の最新ドキュメントを参照できるよう、プロジェクト固有の Context7 設定を行っています。

プロジェクト固有の設定

1. 環境変数の設定

   # .env.mcp.exampleを.env.mcpにコピー
   cp .env.mcp.example .env.mcp
   
   # 実際のAPIキーを設定
   # CONTEXT7_API_KEY=your-actual-api-key
   

2. MCP 設定ファイル .mcp.jsonにプロジェクト専用の Context7 設定が含まれています：

   {
     "mcpServers": {
       "context7-project": {
         "type": "http",
         "url": "https://mcp.context7.com/mcp",
         "headers": {
           "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}",
           "X-Project-Context": "travel-itinerary-nextjs"
         }
       }
     }
   }
   

3. 接続確認

   # MCPサーバー一覧を確認
   claude mcp list
   

   正常に接続されている場合：

   mongodb-readonly: npx -y @mongodb-js/mongodb-mcp-server - ✓ Connected
   context7-project: https://mcp.context7.com/mcp (HTTP) - ✓ Connected
   

対応技術スタック

Context7 から最新ドキュメントを取得可能な技術：

• Next.js 16 (App Router、Server Components)
• React 19 (最新 Hooks、パフォーマンス改善)
• Tailwind CSS 4.x (新機能、ユーティリティ)
• Jotai (状態管理パターン)
• MongoDB & Mongoose (ベストプラクティス)
• Auth0 (認証実装パターン)
• React Hook Form & Zod (フォーム設計)
• TypeScript (型定義、エラーハンドリング)

参考リンク

• MongoDB MCP Server 公式ドキュメント
• Sentry MCP Server - Sentry エラー監視との連携
• Claude Code MCP ガイド
• Model Context Protocol
• Context7 - AI コンテキスト管理サービス