USER GUIDE

Firescope マニュアル

インストールから日々の運用まで、順番に読めばそのまま使いはじめられるガイドです。画像はすべて実際のアプリの画面です。

インストール

ダウンロードから Mac 版の.dmg を取得します(Apple Silicon / Intel を選べます)。
ダウンロードした .dmg を開き、Firescope アイコンを「アプリケーション」フォルダへドラッグします。
アプリケーションフォルダから Firescope を起動します。

Firescope は Apple の署名・公証済みです。「開発元を検証できません」の警告は表示されずにそのまま起動できます。

Windows

ダウンロードから Firescope-Setup.exeを取得して実行します。
初回実行時に SmartScreen の警告が出る場合は、「詳細情報」→「実行」で進めてください。

初期設定(言語とテーマ)

はじめて起動すると、4ステップのセットアップ画面が開きます。まずは表示言語を選びます(日本語・English・简体中文・繁體中文・한국어・Español・Português・Français・Deutsch の9言語を内蔵)。クリックした瞬間に画面へ反映されるので、迷ったら押して確かめてください。

つぎに見た目のテーマを選びます。Light / Dark をはじめ10種類。こちらもクリックでその場でプレビューされます。

言語もテーマも、あとから右下の ⚙ 設定 と🎨 パレット でいつでも変更できます。

Firestore に接続する

接続方法は2つあります。かんたんなのはGoogle アカウントでのサインインで、鍵ファイルの準備が要りません。従来どおりサービスアカウント秘密鍵(JSON)を使うこともできます。

ステップ3: 接続方法を選ぶ(Google / サービスアカウント / エミュレーター)

方法1: Google アカウントでサインインする

Firescope を普段の Google アカウントで認証し、アクセスできる Firebase プロジェクトの一覧から選ぶだけで接続できます。鍵ファイルのダウンロードも保管も不要です。

接続追加ダイアログの「Google」タブで「Google でサインイン」を押すと、ブラウザで同意画面が開きます。
アプリに戻ると、アクセスできる Firebase プロジェクトが一覧表示されます。検索で絞り込み、「表示中の N 件をすべて選択」でまとめて選ぶこともできます。すでに接続済みのプロジェクトは選べません(二重登録を防ぐため「接続済み」と表示されます)。
選んだプロジェクトごとに環境ラベルと読み取り専用を指定します。環境ラベルはプロジェクトID から自動で推定されるので、違うものだけ直せば十分です。
「N件の接続を追加」で確定します。

一部のプロジェクトだけ接続に失敗した場合(Firestore が有効化されていない、権限が足りない等)、成功した分はそのまま接続され、失敗した分だけが選択に残ります。原因を直してからボタンをもう一度押せば、失敗分だけ再試行できます。

Firescope が求める権限は、あなた自身の Firestore と Firebase Authentication の読み書きに必要な範囲だけです。トークンは macOS キーチェーン(Windows は DPAPI)由来の鍵で暗号化して端末内にのみ保存し、外部には送信しません。

方法2: サービスアカウント秘密鍵(JSON)を使う

CI 用のサービスアカウントを使いたい場合や、Google アカウントを使わずに接続したい場合はこちらです。持っていなくても、画面の案内どおりに進めば1分ほどで取得できます。

「サービスアカウント設定ページを開く」を押すと、Firebase コンソールの該当ページがブラウザで開きます(場所: プロジェクトの設定 → サービスアカウント)。
「新しい秘密鍵の生成」をクリックして JSON をダウンロードします。
Firescope に戻り、「JSONファイルを選択して接続」からダウンロードした JSON を選びます。複数プロジェクトの JSON をまとめて選択して同時に接続することもできます。
接続先の環境(開発 / テスト / ステージング / 本番)を選びます。サイドバーで色付きのラベルとして表示され、安全ガードの強さもこのラベルで決まります。

鍵は macOS キーチェーン由来の鍵で暗号化して、この Mac だけに保存されます。外部には送信されません。

ローカルの Firestore エミュレーターにも接続できます。サイドバーの + から「エミュレーターに接続」を選び、ホスト(例: localhost:8080)とプロジェクトIDを入力してください。

接続の整理(グループ・非表示)

接続が増えると、サイドバーのどれがどのプロジェクトか分かりにくくなります。Firescope は並べ替えの操作をしなくても、自動で見出しを付けて整理します。

自動の区分け

接続は、まずどの認証情報で繋いでいるかで区分けされます。

Google アカウント — サインインしたアカウントごとに分かれます。複数アカウントを使い分けていても、どちら由来の接続か一目で分かります
AdminSDK キー — サービスアカウント秘密鍵ごと
エミュレーター — ローカルの Firestore エミュレーター接続

さらに各区分けの中で、接続先名の共通部分ごとにまとまります。末尾のdev / staging / production / test / env といった環境を表す語は取り除いて突き合わせるため、OCEAN-dev・ocean-pro・OCEAN-staging・OCEAN-test は OCEAN という1つの見出しにまとまります(大文字小文字は区別しません)。

見出しを右クリックするか、ホバーで出るアイコンから、そのグループの接続をまとめて切断できます。切断は確認ダイアログを必ず経由します。

使わない接続を非表示にする

接続を切断せずに一覧から隠すことができます。設定や鍵はそのまま残るので、いつでも元に戻せます。

接続を右クリック →「この接続を非表示にする」。グループの見出しからは「このグループを非表示にする」、複数選択(⌘ / Shift クリック)からは「選択した接続を非表示にする」を選べます。
非表示があるとき、サイドバー上部に目のアイコン(件数バッジ付き)が現れます。
そのアイコンを押すと非表示の接続が薄く表示されます。右クリック →「再表示する」で元に戻せます。グループ単位・複数選択でまとめて戻すこともできます。

コレクション検索を使っている間は、非表示にした接続も必ず表示されます。検索して出てこないと「接続が消えた」と誤解してしまうためです。

データを見る

サイドバーの接続を開いてコレクションをクリックすると、ドキュメントが表で表示されます。各列のヘッダーには型バッジ(string / int / time など)が付くので、データの形がひと目でわかります。

行をクリックすると、右パネルにドキュメントの全フィールドが表示されます。
並び替え・表示件数・グループ検索(コレクショングループ)はツールバーから変更できます。
読み取り件数はステータスバーに常時表示されます(課金の目安に)。

⌘P コレクション名で横断ジャンプ

⌘K ドキュメントIDで横断検索

⌘F 表の中を検索(テーブル内検索)

⌘⇧F サイドバーのコレクション検索へフォーカス

コマンドパレット(⌘K)

⌘K でどこからでも呼び出せる横断検索です。コレクション名・接続名・画面・「最近見た」/ ブックマークを一気に検索でき、6文字以上の文字列を入力するとドキュメントIDでの横断検索も候補に出ます。

↑↓ で候補を移動、Enter で実行。マウスに手を伸ばさずに画面を切り替えられます。
テーマの切り替えや値マスキングのON/OFF、設定・ショートカット一覧を開くなど、よく使う操作もここから呼び出せます。

テーブル内検索(⌘F)

表を開いた状態で ⌘F(Windows は Ctrl+F)を押すと、表の全セルを横断する部分一致検索ができます。ヒットしたセルは琥珀色にハイライトされ、Enter を押すたびにカーソルがスムーズスクロールで次のヒットへ移動します。

ID を含むすべての表示列が対象です(大文字小文字は区別しません)。
Enter で次へ、Shift+Enter で前へ。末尾まで行くと先頭に戻ります。
ヒットしたセルはそのまま選択状態になるので、矢印キーでの移動や ⌘C・F2 での編集を続けられます。
全件読み込み前は、読み込み済みの範囲だけが検索対象です(件数の横に * が付きます)。
サイドバーのコレクション検索は ⌘⇧F になりました(表を開いていない画面では従来どおり ⌘F でも移動します)。

クエリの強化

組み立てたクエリ条件は保存クエリとして名前を付けて保存でき、いつでも一覧から呼び出せます(条件・並び替え・件数をまとめて復元)。

数値(int / double)フィールドを選ぶと、現在のフィルタ適用後の合計・平均をツールバーに表示します。

「チャート」では、読み込み済みドキュメントから数値フィールドはヒストグラム、文字列/enumフィールドは出現頻度(上位10件)を即座に描画します。追加の読み取りは発生しません。

「コード生成」では、組み立てた条件を firebase-admin(Node.js)のコードとしてコピーしたり、複合インデックスが必要な条件ならfirestore.indexes.json 形式の定義としてコピーできます。

論理名(項目名の翻訳表示)

carryingOutCoffinMasterId のような英語のフィールド名を、日本語などの論理名で表示できます。ツールバーの「論理名」トグルでいつでも物理名⇔論理名を切り替えられます。

辞書はツールバーの 📖 アイコンから編集します。適用範囲は「接続全体で共通」と「このコレクションのみ(上書き)」の2層です。
「自動翻訳」で内蔵辞書+無料翻訳 API により空欄を一括入力できます。
「Google 翻訳を開く」を押すと、フィールド名を英文化した状態で翻訳ページが開き、訳文をコピーしてアプリに戻るだけで一括反映されます。
列ヘッダーを右クリック →「論理名を設定…」で、その列だけをすぐ編集できます。
ヘッダーの型バッジ(string / int など)は「型表示」トグルで表示/非表示を切り替えられます。

論理名は表示だけの機能です。CSV エクスポートやクエリは物理名のまま動くので、データの互換性には影響しません。

タブとグループ

コレクションを右クリック →「新しいタブで表示」で、ブラウザのようにタブを増やせます。タブは Chrome のようにグループへまとめられます。

タブを右クリック →「新しいグループに追加」でグループを作成。名前と色を付けられます。
グループのチップをクリックすると折りたたみ/展開。
タブのダブルクリックで名前と背景色を変更できます。
ドラッグ&ドロップで並べ替え・グループへの出し入れができます。
タブの状態は再起動後も復元されます(設定でOFFにできます)。

分割ビュー

コレクションを右クリック →「右に分割して表示」で、2つのコレクションを左右に並べられます。マスタとトランザクションの突き合わせに便利です。

サイドバーからコレクションを画面の左右端へドラッグしても分割できます。
ペインのチップをドラッグすると、左右の入れ替えや新しいタブへの取り出しができます。
分割状態はタブごとに保持されます。

リアルタイム監視

ツールバーの「監視」を押すと、表示中のコレクションの変更がグリッドへライブ反映されます。別のアプリやサーバーが書き込んだ内容が、リロードなしでそのまま流れ込みます。

開始前のダイアログで、条件(フィールド・値)・並び替え・件数を絞り込めます。
右側の変更フィードに「追加 / 更新 / 削除」が時系列で並び、変更されたフィールド名も表示されます。
監視は読み取り専用です。監視中の書き込み操作は通常どおり安全パイプラインを通ります。
同時に監視できるのは5件までです。
指定時間が経つと自動停止します(設定で時間を変更可能)。読み取り回数の使いすぎを防ぎます。

監視できるのは条件に一致する先頭 N 件のウィンドウです。大きいコレクションでは条件で絞るか、updatedAt の降順で並び替えると「最新の変更」を追いやすくなります。

データを編集する

セルをダブルクリックするとその場で編集できます。Enter で確定、Esc でキャンセル。 int や timestamp などの型は保たれたまま書き込まれます。

すべての書き込みは安全パイプラインを通ります:

確認 — 環境ラベル × 操作の危険度に応じたダイアログが出ます。本番の破壊的操作はプロジェクトIDのタイプ入力が必要です。
自動バックアップ — 影響を受けるドキュメントが実行前にスナップショットされます。
実行 — 書き込みが行われます。
操作ログ — 成否を問わず記録されます(下部バーの「操作ログ」から確認)。

「本番」ラベルの接続では削除・一括更新などの確認が最も厳しくなります。調査だけなら接続を読み取り専用にしておくと安心です(接続を右クリック → 読み取り専用)。

バックアップと復元

破壊的操作の直前に取られたスナップショットは、下部バーの「バックアップ」にたまっています。選ぶと復元プレビューが開き、再作成 / 上書き / 変更なしの差分を確認してから復元できます。

⌘Z(またはサイドバーの ↩︎ アイコン)で直近の書き込みをすぐ復元できます。
スナップショットは世代上限を超えると古いものから消えます。残したいものはピン留め 📌 してください。

コンソール

サイドバーの「コンソール」では、firebase-admin 風の JavaScript でクエリを書けます。⌘Enter で実行すると、結果が型注釈つきの表で表示されます。

const snap = await db.collection('orders')
  .where('status', '==', 'paid')
  .orderBy('amount', 'desc')
  .limit(20)
  .get();
return snap.docs.map((d) => ({ id: d.id, ...d.data() }));

マウス派にはビジュアルビルダー(取得 / 更新 / 作成 / 削除)もあります。組んだ条件は「コードに反映」でJSに変換できます。
書き込みを含むコードはドライラン → 書き込みプレビュー → 適用の順で実行されるので、いきなりデータが変わることはありません。
join(結合)表示にも対応しています。

CSV 入出力

エクスポート

コレクションのツールバーの「CSV出力」を押すと、いま表示しているクエリ結果(フィルタ・並び替え反映済み)をCSVに保存できます。ヘッダーに型注釈が付くので、あとで再インポートしても型が崩れません。

インポート

ツールバーの「インポート」→ CSVファイルを選択します(Shift_JIS も自動判定)。
列ごとの型と、モード(upsert / 新規のみ / 更新のみ)を確認します。
「件数を確認」で新規・上書きの件数をプレビュー。
「インポート実行」→ 確認ダイアログを経て取り込まれます。上書き分は実行前に自動バックアップされます。

スキーマチェック(スキーマ崩れ検出)

コレクションを右クリック →「スキーマチェック…」で、コレクション全体を読み取って型が混在するフィールド・一部のドキュメントだけ欠けているフィールド・タイプミスの可能性がある稀なフィールドを自動検出します(上限 20,000 件)。

同じドキュメント群でまとめて欠けているフィールドは1枚のカードに集約されます。「まとめて開く」で該当行すべてにチェックが付き、そのまま一括削除などに進めます。
該当ドキュメントの ID をクリックすると、グリッドの該当行まで自動スクロールしてハイライトされます。
結果はウィザードを閉じても保持されるので、ドキュメントを確認しながら何度でも行き来できます。
Zod スキーマ検証タブでは、Zod スキーマ(TypeScript)を貼り付けて全ドキュメントを検証できます。

スキーマで書き込みを守る

スキーマチェックの「Zodスキーマ検証」タブでは、検証だけでなく書き込み時の強制も設定できます。なし / 警告 / ブロックの3段階から選び、ブロックにするとスキーマに違反する書き込みをメインプロセスで拒否します(UIを迂回しても防がれます)。強制はそのコレクションパスに完全一致するドキュメントにのみ適用されます。

Zodスキーマを登録しておくと、新規ドキュメント作成時に「フォーム入力」モードが使えます。スキーマの型からフォームが自動生成されるので、JSONを手書きせずに必須項目を埋めるだけで作成できます(スキーマが未登録のコレクションでは、スキーマチェックの型推定からフォームを組み立てることもできます)。

ER図の出力

サイドバーの接続を右クリック →「ER図を出力…」で、全コレクションをサンプリング(各最大100件)してER図を自動生成します。 reference フィールドとサブコレクションに加えて、customerId のような文字列IDの参照もフィールド名から推定して点線のリレーションとして描きます。

「フィールドを表示」「キーのみ」「型を表示」「論理名を含める」をクリックで即切り替え(全パターンを先に生成しておくため待ちません)。
ピンチ / Ctrl+ホイールで拡大縮小、ドラッグでパン。ワンクリックで全体表示に戻せます。
Mermaid テキストのコピーと .mmd / .svg 保存に対応。GitHub や Notion にそのまま貼れます。
サブコレクションが多い親への線は、見やすさのため図では省略されます(Mermaid テキストには含まれます)。

データ移行

「一括更新」では、フィールドの一括セットに加えてフィールド名の変更・型変換もできます。実行前は必ず dry-run プレビューで全件の diff を確認してから実行します。

コレクションを右クリック →「コレクションを削除…」はサブコレクションを含めて再帰的に削除します。確認ダイアログの件数にはサブコレクション分も含まれ、実行前に対象ドキュメントが自動でスナップショットされます。

「シードデータ生成」は、既存ドキュメントの型分布(スキーマチェック)からフィールド構成を推定し、ダミードキュメントを指定件数まとめて作成します。開発・エミュレーターでの動作確認用の機能です。

環境の比較とコピー

他の環境と比較

コレクションを右クリック →「他の環境と比較…」で、開発と本番など2つの環境の同名コレクションを突き合わせられます。差分(追加 / 削除 / 変更)がドキュメント単位・フィールド単位で一覧されます。

updatedAt など、比較から除外するフィールドを指定できます。
差分の内容は CSV として書き出せます。

他の環境にコピー

「他の環境にコピー…」では、コレクションを別の接続(環境)へ複製できます。実行前に件数と上書きの有無をプレビューし、本番への書き込みは通常どおり厳格な確認ガードを通ります。

比較と差分

環境の比較では、差分(内容が異なる/片方にしかないドキュメント)を選んでそのまま書き込み先へ反映できる差分同期にも対応しています。同期の方向は接続の環境ラベルをもとに提案され、反映は通常どおり安全パイプライン(確認・自動バックアップ)を通ります。

ドキュメント右パネルの「比較」ボタンでは、開いているドキュメントと任意のドキュメント(別コレクション・別接続も可)をフィールド単位で比較できます。

ドキュメントの「変更履歴」では、自動バックアップを版として時系列に並べ、任意の2版(現在を含む)を選んで差分を比較できます。

Authentication ユーザー

サイドバーの「Authentication」から、Firebase Authentication のユーザーを一覧・管理できます。

メール・表示名・プロバイダ・作成日・最終ログインを一覧表示。論理名トグルで項目名の日本語表示もできます。
ユーザーの無効化 / 有効化・削除、パスワードリセットメールの送信に対応。
ユーザーの UID をコピーして、Firestore 側のドキュメントとの突き合わせに使えます。
破壊的操作(削除など)は Firestore と同じ安全パイプライン(確認 → 操作ログ)を通ります。

共有ログ(誰が・いつ・何を)

書き込み操作のメタデータをプロジェクトの Firestore に記録し、同じプロジェクトに接続する全員で「誰が・いつ・何をしたか」を共有できます。

サイドバーで接続を右クリック →「共有ログを記録」で有効化します(接続ごとのオプトイン)。確認ダイアログで内容の説明と、操作者の表示名の設定がその場で完結します。
記録されるのはメタデータのみ(操作者名・操作種別・対象パス・成否・所要時間)。ドキュメントの値は一切含まれず、外部サーバーにも送信されません(保存先はそのプロジェクトの _firescope_audit コレクション)。
閲覧は操作ログ →「共有ログ」タブ。日付ごとのタイムライン・操作者/種別/期間のフィルタ・行クリックで詳細を表示し、対象のドキュメントをグリッドで直接開けます。
ログは30日を過ぎると自動的に削除されます。

操作者の表示名は設定 → プロフィールでいつでも変更できます。表示名を設定せずに記録された操作は PC 名で表示されます。

運用

リアルタイム監視には条件アラートを設定できます。「追加されたら」「削除されたら」「指定フィールドが変わったら」を登録しておくと、一致した変更でデスクトップ通知が届きます。

フッターの読み取り数をクリックすると、セッション中の概算読み取り件数・概算課金額・推移がポップオーバーで確認できます。

設定の「共有・引き継ぎ」タブでは、フィールド論理名・保存クエリ・ブックマークなど一部のUI設定を1つのJSONファイルに書き出し/読み込みできます。接続の秘密鍵・ライセンス情報・環境ラベルは一切含まれないので、チームでの共有や機種変更に使えます。

ツールバーの「値を隠す」をONにすると、項目名・型・構造はそのままに実データだけを伏せ字(••••)で表示します。画面共有やスクリーンショットのときに便利です(表示だけの機能で、実データは変更されません)。

MCP サーバー(AIエージェント連携)

Firescope には MCP(Model Context Protocol) サーバーが同梱されています。Claude Code などのAIエージェントから接続すると、会話の中で Firestore のコレクション一覧・ドキュメント取得・クエリ実行をそのまま行えます。

v1 は読み取り専用です。破壊的操作を必ず安全パイプラインに通すという設計上、書き込み系のツールはあえて提供していません。

起動(リポジトリ直下で):

# エミュレーターに接続する場合
FIRESCOPE_MCP_PROJECT_ID=your-project \
FIRESCOPE_MCP_EMULATOR_HOST=127.0.0.1:8080 \
npm run mcp

# サービスアカウントJSON経由で実プロジェクトに接続する場合
FIRESCOPE_MCP_SERVICE_ACCOUNT_PATH=/path/to/service-account.json \
npm run mcp

MCP クライアント側の設定例(.mcp.json):

{
  "mcpServers": {
    "firescope": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/path/to/firescope",
      "env": {
        "FIRESCOPE_MCP_SERVICE_ACCOUNT_PATH": "/path/to/service-account.json"
      }
    }
  }
}

提供ツールは3つ:コレクション一覧(firestore_list_collections)・ドキュメント取得(firestore_get_document)・クエリ実行(firestore_query_collection、フィルタ/ソート/件数上限に対応)。
GUI のクエリビルダーと同じ内部ロジックを再利用しているため、結果の形はアプリの表示と一致します。

アップデート

更新は6時間ごと+起動時に自動確認されます(設定 → 情報の「更新を確認」で手動確認も可能)。
必須アップデートが公開された場合は、起動時のアップデート画面から自動でダウンロード → 再起動 → 適用まで行われます。ボタン操作は不要です。
失敗した場合(オフライン等)のみ、ブラウザからの手動ダウンロードが案内されます。

料金とライセンス

初回起動から 14日間はトライアルとして全機能を使えます。登録も支払い情報も不要です。
期限が切れても、データの閲覧は引き続き無料で使えます。
購入はアプリ内から:右下の ⚙ 設定 → ライセンスでプラン(Pro / TEAM、月額 / 年間)を選ぶと、ブラウザで Stripe の決済ページが開きます。決済が終わるとアプリが自動でライセンスを有効化します。
別の Mac へ移るときは、旧マシンで「ライセンスを解除」してから新マシンでアクティベートしてください。

プランの詳細は料金ページをご覧ください。

よくある質問

接続できない / 「認証に失敗しました」と出る: JSON が対象プロジェクトのサービスアカウント鍵か確認してください。鍵を作り直した場合は、古い接続を切断して新しい JSON で接続し直すのが確実です。
データはどこかに送信されますか?: いいえ。Firescope はあなたの Mac から Firestore に直接アクセスします。鍵もデータも外部のサーバーには送信されません。
「本番ガード」って何をしてくれるの?: 接続の環境ラベルと操作の危険度に応じて、確認の強さを自動で変えるしくみです。たとえば本番でのコレクション削除は、プロジェクトIDを手で入力しないと実行できません。UI の注意書きではなくアプリの中核(メインプロセス)で検証しているため、うっかりでは突破できません。
Windows 版はありますか?: はい。ダウンロードページからFirescope-Setup.exe を取得してください(SmartScreen の警告が出た場合は「詳細情報」→「実行」で進めます)。
言語を追加できますか?: はい。設定 → 言語から言語パック(JSON)を書き出して翻訳し、取り込むことで任意の言語を追加できます。