jsonloupe

jsonloupe は、一般的なビューアでは大きすぎたり、精度が足りなかったりする JSON ドキュメントの確認、差分比較、編集、クエリに使えるブラウザベースの ワークベンチです。スプレッドシートへの変換にも対応しています。ネストされた JSON を入力すると、リンクされたテーブルを 1 つの .xlsx ファイル、または CSV の zip ファイルとして出力します。各ファイルについて確認する内容は プレイブック内のチェックとして保存できます。1 回の操作で、開いている ドキュメントに対してすべてのチェックを実行でき、同じファイルで jsonloupe check を使って CI をゲートできます。データがマシンの外に出ることは ありません。ブラウザ内では、ドキュメントはウェブワーカーで解析され、 IndexedDB に保存され、どこにもアップロードされません。バックエンドも、 アカウントも、テレメトリーもありません。

実行する

jsonloupe.dev でホスト版アプリを使うか、マージのたびに main から再ビルドされます。または、最新の npm リリースを自分のマシンで 完全オフラインで実行できます。

npx jsonloupe

これにより、ループバック専用の静的サーバー（127.0.0.1:5199、または次に 利用可能なポート）が起動し、パッケージに含まれるビルド済みアプリを配信します。 実行時の依存関係もネットワーク呼び出しもありません。コメントを含めて約 200 行の、 監査可能な単一ファイルです：bin/jsonloupe.mjs。 --port <n> と --no-open は名前のとおりに動作します。--key-file <path> を指定すると、 そのファイルのモデルキーをループバック経由のみでページに配信します。同じコマンドで コンバーターの動詞（inspect、draft、convert、後述）と CI ゲート（check、後述）も利用できます。 npx jsonloupe --help で一覧を確認できます。

なぜ新しい JSON ビューアーなのか？

• 数値を損失なく扱えます。 2^53 を超える Int64 ID（snowflake／注文／エンティティ ID）や精度の高い小数は、貼り付け → 表示 → 編集 → コピー → ダウンロードの間も正確な桁が保たれます。浮動小数点数に変換されることはありません。
• 巨大なドキュメント向けに設計されています。 ツリーは仮想化され、展開はチャンク単位で行われるため（[0 … 9999] の範囲行）、500 万要素の配列も瞬時に開けます。解析、差分比較、検索、圧縮はすべて UI スレッド外で実行されます。
• 圧縮ペイロードを標準でサポートします。 生の .zst、Base64-Zstd（標準形式または URL セーフ形式）、PostgreSQL の \x… bytea を貼り付けるかドロップすると、自動検出され、ワーカー内でデコードされて、変換トレース付きのドキュメントとして開きます。エンコーダーと転送サイズインスペクター（編集可能な予算に対して UTF-8／Zstd／Base64／エンベロープの正確なバイト数を表示）を使えば、逆方向への変換もできます。
• ネストされた JSON を、手元のマシンでスプレッドシートに変換できます。 繰り返し配列やオブジェクトマップは、リンクされた独自のテーブルになります。orders と order_items は order_id で結合され、items/0/sku のような列にはなりません。何かを書き込む前に実際の行を確認でき、マッピングは小さなファイルとして保存されます。モデルを使わず、翌月のファイルからも同じ列を生成できます。
• セマンティック差分。 ID ベースの配列アラインメント（id、複合キー、または自動検出による照合）を使って左右に並べて比較できるため、配列の並べ替えによる誤検出が大量に発生しません。キーまたはパスのプレフィックスを指定して、ノイズの多いフィールドを無視できます。
• 本格的なクエリ言語。 述語と集計パイプ（$.tasks[?(@.status == 'FAILED')] | group(@.failureReason)）に対応する JSONPath のサブセットを、入力中にライブプレビューしながらローカルで実行できます。数値リテラル、述語、合計、平均、最小値、最大値は、int64 と精度の高い小数でも正確に保たれます。
• 合否判定に使えるチェック機能。 各ファイルに対して確認したい内容を、クエリと期待する件数の組み合わせでチェックとして保存できます。ワンプレスですべてを判定し、失敗ごとに該当する最初のパスを示します。完了できなかった件数は「判定不能」となり、根拠なく合格にはなりません。同じプレイブックファイルを使って、jsonloupe check で CI を、MCP の run_checks でエージェントを判定できます。

クイックスタート

git clone https://github.com/priyanshuN/jsonloupe && cd jsonloupe
npm ci
npm run dev        # http://localhost:5199

ランディングページに JSON を貼り付けると、瞬時に解析され、ローカルメモリに保存されます（「最近使った項目」サイドバーから再度開く、ピン留め、削除ができます）。末尾のカンマ、一重引用符、Python リテラル、途中で切れたログの抜粋など、不正な入力は自動修復され、元のバイト列を保持したままフラグが付けられます。

機能紹介

• ツリー／コード／分割ビュー — 仮想化されたツリー、編集可能なCodeMirrorコードビュー（折りたたみ、検索、⌘Sで適用）、または左右に並べた両方のビューで、クリックした行への同期に対応します。ツリー内でインライン編集でき、編集内容全体を元に戻す／やり直すことができます。小さなドキュメントは画面いっぱいに展開して表示され、深くスクロールすると、現在の位置に含まれる親キーがツリーの上部に固定されます。
• コマンドパレット — どこからでも⌘K／Ctrl Kを押し、ビュー、アクション、テーマ、最近開いたドキュメントの名前を数文字入力して、Enterキーを押します。
• 配色 — ダークテーマはTokyo Night、Catppuccin Mocha、Dracula、Gruvbox、GitHub Dark、ライトテーマはSolarized Light、Catppuccin Latte、Rosé Pine Dawn、GitHub Lightに対応し、jsonloupe独自の配色も用意しています。サイドバーの選択メニューで配色にカーソルを合わせる（または⌘Kで矢印キーを使って選ぶ）と、アプリ全体で試せます。モードごとに配色が保存されるため、「システムに従う」に設定すると、日没時に2つの配色が切り替わります。すべての配色はWCAG AAのコントラスト基準を満たしており、CIでチェックされています。
• 検索とフィルター — /で検索します（リテラル検索または/regex/i）。フィルターモードでは、一致するブランチだけがツリーに表示され、終了後は展開状態が復元されます。
• パスと識別 — パンくずリストからJSONPath、JSON Pointer、またはJSアクセサーとしてワンクリックでコピーできます。「同じ値」では、その値を持つすべてのノードに移動できます（スキーマ不要の相関IDトレース）。
• 値のレンズ — エポック時刻をローカル日時と「3日前」に変換し、ISOタイムスタンプも同じ形式の相対時間で表示します。色文字列にはカラーチップを、緯度／経度、uuid／url／base64にはフラグを表示します。また、折りたたまれたコンテナーにはバイト数を表示するため、容量の大きいノードもひと目で見つけられます。
• テーブルとCSV — 配列を並べ替え可能なテーブルビューで表示します。テーブルやクエリ結果を、桁を正確に保ったCSV（RFC 4180）としてエクスポートできます。
• プレイブック — チェックと関数を1つのシートで管理 — チェックはクエリと期待される件数（0件、最大3グループ、1～10件など）で構成されます。run allを実行すると、開いているドキュメントに対してすべてのチェックを判定し、失敗ごとに原因となった最初のノードを示します。関数は、クエリ言語では対応しにくい問いに答えるJavaScriptコードです。ネットワークを無効にしたサンドボックスで実行されます。複数の関数を選択して1回実行すれば、すべての結果が1つのレポートにまとめられます。同じチェックをjsonloupe checkでCIのゲートとして実行できます。 （以下を参照。）
• JSON → Excel／CSVコンバーター — 列の名前変更や並べ替え、ソースフィールドの選択、定数の追加、日付と座標の処理方法の設定ができます。出力先CSVのヘッダーから列名を取得し、次のファイル用にマッピングを保存または共有できます。 （以下を参照。）
• ファイルハンドル — .json／.jsonl／.zstファイルをドロップできます。再読み込みするとディスクから読み直し、表示中のバージョンからの変更内容を示します。
• クエリ — JSONクエリをローカルで実行し、便利なクエリを保存したり、結果を再利用可能なチェックに変換したりできます。オプションの英語 → クエリモードでは、ドキュメントの構造（フィールド名／型のみ。値は使用しません）だけを使って質問を翻訳し、生成されたクエリを確認してからローカルで実行できるよう、処理を一時停止します。接続方法は選べます。キーを貼り付けずにOpenRouterで認証するか、手動キーの詳細オプションを使います。キーを貼り付けるか、ローカルファイル（生のキーまたは.envの行）から読み込めます。ページ内で読み込まれ、アップロードされることはありません。明示的に接続するまでは、この機能は動作しません。開示パネルには送信内容が正確に記録されます。SECURITY.mdを参照してください。

ブラウザーで使うクエリの例

ドキュメントを開いてqueryを押し、JSON queryを選択したまま、クエリを貼り付けます。このタブ内で直接実行されるため、APIキーは不要で、モデルにデータが送信されることもありません。

次の小さなドキュメントを使います。

{"tasks":[
  {"id":9007199254740992,"status":"FAILED"},
  {"id":9007199254740993,"status":"READY"}
]}

• 失敗した行をフィルターします。

  $.tasks[?(@.status == 'FAILED')]
  

  結果：一致は1件、$.tasks[0]です。

• ステータスごとに行数を数えます。

  $.tasks[*] | group(@.status)
  

  結果：FAILED 1、READY 1です。

• JavaScriptの安全な範囲を超える整数を丸めずに比較します。

  $.tasks[?(@.id > 9007199254740992)] | count
  

  結果：1 — 正確な9007199254740993のIDだけが大きい値です。

ネストされた JSON をリンクされたテーブルに変換

スプレッドシートだけが目的なら、 jsonloupe.dev/json-to-excel.html に 専用ページがあります。貼り付けて、変換すれば完了です。

ドキュメントを開き、ツールバーのツールグループにあるテーブルのグリフを押します （convert。ここにある各グリフの名前は、ホバーすると表示されます）。繰り返し出現する配列はそれぞれ独立したテーブルになり、データ内にもともとある ID で親に結び付けられます。つまり、次のデータは次のようになります。

{ "orders": [
    { "id": 7, "cust": "ACME",
      "items": [ { "sku": "A", "qty": 2 }, { "sku": "B", "qty": 1 } ] } ] }

items/0/sku のような列が並ぶ 1 行のシートではなく、2 つのシートになります。

orders                    order_items
id  cust                  order_id  sku  qty
 7  ACME                         7  A      2
                                 7  B      1

jsonloupe がテーブルを見つけますが、推測をそのまま実行することはありません。列名の変更、保持するフィールドの選択、日付と座標の読み取り方法の指定を行う間、マッピングと実データのプレビューが画面に表示されたままになります。確定した内容は小さなマッピングファイルとして保存されます。このブラウザーに保存するか、エクスポートするか、コマンドラインから使用できます。

jsonloupe inspect payload.json          # what tables are in here?
jsonloupe draft   payload.json -o payload.spec.json   # a first mapping, to read
jsonloupe convert payload.json --spec payload.spec.json -o payload.xlsx

同じマッピングを使えば、ブラウザー、CLI、MCP サーバーのどれでも同じ列が生成され、処理にモデルは関与しません。マッピングを固定するのはそのためです。セルに入るのは、ドキュメントにあった値そのものです。日付は並べ替えや減算ができる実際の日付になり、数値と座標は数値になります。数値に見えるだけのテキストはテキストのままなので、"1.10" の末尾のゼロは保持され、int64 の ID も丸められず、すべての桁が保持されます。Excel の制限や、列で読み取れない値は報告または拒否され、誤った値が黙って書き込まれることはありません。

プレイブック：関数とチェックをファイルに保存

ドキュメントは日々変わりますが、そこに対して尋ねる少数の質問は変わりません。そのため、ツールバーの playbook（1.8 より前は functions ビュー。⌘K でもその単語で引き続き検索できます）を開くと、ドキュメントの横に 1 つのシートとして表示されます。そこには、クエリと期待される件数をまとめた checks と、名前順に並んだ functions があります。プレイブックを開いた状態で run all（⌘⇧↵ / Ctrl ⇧↵。もう一度押すと停止します）を実行すると、開いているデータ全体で各チェックを評価し、その結果を各行に表示してから、チェックを付けた関数を実行します。 最初に不合格となった行が自動的に開き、最初に一致したノードが表示されます。パスを押すと、横にあるツリーでそのノードが選択されます。シートはそのままの位置に留まります。

チェック

シートで + check を押すか、クエリの結果を save as check でチェックに変換します。チェックでは一致数を数えます。| group ではグループ数を、| distinct では個別の値の数を数え、件数が期待値を満たすと合格します。

合格条件	expectation	Playbook バージョン
一致するものがない	{"type": "no-matches"}	3
1 件以上一致する	{"type": "at-least-one"}	3
正確に N 件見つかる	{"type": "exact-count", "count": N}	3
N 件以下見つかる	{"type": "at-most", "count": N}	4
N 件以上見つかる（N ≥ 1）	{"type": "at-least", "count": N}	4
M 件から N 件まで見つかる（両端を含む）	{"type": "between", "min": M, "max": N}	4

件数は JavaScript の安全な範囲内の整数でなければなりません。その範囲を 1 でも超える値は拒否され、丸められることはありません。クエリの末尾が | sum、| avg、| min、| max の場合、件数ではなく単一の値が返されます。そのため、そのクエリに対するチェックは、数えることを意図していない値を判定するのではなく、実行できなかったと表示します。

各チェックの結果は ✓ pass、✕ fail、? inconclusive、✗ could not run のいずれかです。「結論が出ない」は、誠実な第 3 の結果です。| group と | distinct では、最大 100,000 件のグループまたは値が保持されます（カーディナリティ上限）。これを超えた場合、件数は下限、つまり少なくとも 100,001 件としか分かりません。下限だけで期待値を証明できる場合（1 件以上、またはすでに到達している N 件以上）は合格となり、すでに上限を超えている場合（一致なし、または 100,000 件以下）は不合格となります。それ以外は結論が出ません。根拠がないのに合格と報告することはありません。クエリを絞り込んで判定してください。

チェックのクエリで指定されているフィールドが開いているドキュメントに存在しない場合、そのことがチェックの行に表示され、パネルには「これは status を読み取ります。このドキュメントにはそのフィールドがないため、合格しても何も証明できない可能性があります」と表示されます。「一致なし」チェックは、フィールド名が変更されたファイルでも同様に合格します。

保存済みのチェックには、直近の判定が 1 件保存され、一致したパスが最大 5 件と、それぞれの短いプレビューが含まれます。チェックは最後に実行したドキュメントに紐づきます。別のドキュメントで実行すると、その結果で置き換わります。実行したドキュメントを再度開くと判定結果は残っていますが、編集すると「ドキュメントを編集済み」と表示されて薄くなり、再実行するまで更新されません。この記録はこのブラウザー内に保持され、エクスポートしたプレイブックに書き込まれることはありません。また、ドキュメントを削除すると記録も削除されます。

関数

関数は読み取った内容を学習します。初めて実行するときは、記録用プロキシを通してドキュメントが渡され、実際に参照したパスが関数とともに保存されます。これにより、実行ボタンを押す前にシートで

orders、orders[].deliveredInHours を読み取ります — このドキュメントにはありません

と表示できます。空の結果を「今日は該当なし」と解釈してしまうこともありません。これは常に注意書きであり、実行を妨げるものではありません。読み取り内容がわかるのは、その実行で通った分岐だけなので、実行ボタンは引き続き使えます。複数の関数にチェックを入れて run all を実行すると、関数名をキーにした単一のオブジェクトとして、すべての結果が返されます。関数の見出しにある open report を押すと、今日のレポートが表示されます。このレポートはダウンロードして、ほかのドキュメントと同じように開き直せます。関数の結果は、そのドキュメントを開いている間は保持されます。別のドキュメントを開くか、再読み込みすると、その行には未実行と表示されます。どの関数にチェックが入っているかは、このブラウザーに記憶されます。

スクリプトは一時的なワーカーで実行されます。ユーザーコードが実行される前に fetch、XMLHttpRequest、WebSockets、IndexedDB、importScripts、ネストされたワーカーが取り除かれ、結果が返された時点、または10秒後に終了します（チェックを入れた一括実行では、その10秒を共有し、制限時間を超えた実行があると全体が停止します）。貼り付けたスクリプトからネットワークや、開いているドキュメントにアクセスすることはできません。JavaScript 数値モードでは既存の関数の動作が維持され、ドキュメントに丸められる値が含まれている場合は、その旨が表示されます。一方、exact text モードでは、そのような安全でないリテラルが元の数字の文字列（"9007199254740993"）として関数に渡されます。3 や 1.5 などの通常の値は引き続き数値として扱われるため、通常の集計や計算はそのまま行えます。このモードはブラウザーの設定としてではなく、関数とともに保存およびエクスポートされます。

ファイル

プレイブックは、再利用できる作業をファイルにしたものです。質問と期待値が含まれますが、データは含まれません。

{
  "playbookVersion": 4,
  "name": "carrier dumps",
  "functions": [
    {
      "name": "slow orders",
      "script": "data.orders.filter(o => o.deliveredInHours > 48)",
      "reads": ["orders", "orders[].deliveredInHours"],
      "numberMode": "exact-text"
    }
  ],
  "checks": [
    {
      "name": "no failed orders",
      "query": "$.orders[?(@.status == 'FAILED')]",
      "expectation": { "type": "no-matches" }
    },
    {
      "name": "a full day of orders",
      "query": "$.orders[*]",
      "expectation": { "type": "at-least", "count": 1000 }
    },
    {
      "name": "a handful of carriers",
      "query": "$.orders[*] | group(@.carrier)",
      "expectation": { "type": "between", "min": 1, "max": 5 }
    }
  ]
}

プレイブックバーの export を使うと、バージョン3としてファイルが書き出されます。ただし、チェックでバージョン4が必要な場合は例外です。at-most、at-least、between のチェックがないライブラリは、jsonloupe 1.4～1.7で読み込めるバージョン3として書き出されます。import を使うか、ファイルをウィンドウにドロップすると、その内容が追加されます。インポートではマージされ、置き換えは行われません。すでに使用している名前はそのまま残り、インポートされた項目には slow orders 2 のような名前が付けられます。重複は忘れる操作ひとつで解決できますが、上書きは元に戻せないためです。不明なフィールドは破棄せず、名前を示して拒否されます。そのため、新しいバージョンのjsonloupeで作成されたファイルを一部だけ取り込んで、インポートが成功したように見せることはありません。ライブラリには関数とチェックをそれぞれ100件まで保存できます。101件目の保存は、その旨を示すメッセージとともに拒否されます。収まりきらないプレイブックも、古い項目を押し出すのではなく、全体が拒否されます。バージョン1、2、3のプレイブックも引き続きインポートできます。バージョン1の関数は、元のJavaScript数値モードを維持します。

CI での jsonloupe check

同じチェックをパイプラインのゲートとして使えます。jsonloupe check は、ブラウザーと同じエンジンでプレイブックのチェックを 1 つ以上のファイルに対して実行し、失敗があれば 0 以外の終了コードを返します。

npx -y jsonloupe@^1.8.0 check carrier-dumps.playbook.json out/orders.json

out/orders.json · 3 checks · 4 ms
  ✕ no failed orders — Fail — 2 matches; expected no matches
      first: $.orders[312]
             $.orders[877]
  ✓ a full day of orders — Pass — 1,204 matches; expected at least 1,000 matches
  ✓ a handful of carriers — Pass — 3 groups; expected between 1 and 5 groups
1 function not run — functions run only in the browser
✕ 1 failed · ✓ 2 passed

@^1.8.0 はそのままにしてください。1.8 より前の jsonloupe には check コマンドがありません。その場合は代わりにビューアーのローカルサーバーが起動し、終了しないため、ランナーがタイムアウトするまでジョブが停止します。1.8 以降では、jsonloupe が認識しない単語を指定すると、何も起動せずに 1 で終了します。

最初にプレイブックを指定し、その後に任意の数のファイルを指定します。ファイルは .json、.jsonl／.ndjson、生の Zstd、または Base64-Zstd／bytea ペイロードに対応し、ブラウザーと同じ方法で判別されます。有効な JSON ではないファイルは、裏で修復されることなくゲートで失敗します。修復後のドキュメントをチェックするには --allow-repair を指定します。すべてのクエリは、ファイルを読み込む前にチェックされるため、最後のチェックにタイプミスがあっても解析コストはかかりません。関数は JavaScript であり、ブラウザーのサンドボックス外で実行されることはないため、check は関数を数え、実行しなかったことを示します。CI ログは公開されることが多いため、テキストレポートには一致したパスが出力され、値は出力されません。パスには通過するキーが含まれるため、メールアドレスやアカウント ID をキーとするドキュメントでは --no-evidence を指定してください。--format json は、プログラムが読み取れるよう、一致した各ノードの短いプレビューを含む 1 つのオブジェクトを出力します。--max-evidence N（0～100、デフォルトは 3）または --no-evidence を指定すると、失敗したチェックで示すパスの数を設定できます。

終了ステータス	意味
0	すべてのファイルですべてのチェックに合格しました
1	使用方法のエラー、読み取れなかったファイルまたはプレイブック、または有効な JSON ではないファイル（修復が必要なファイルを含む）
2	プレイブックが有効な JSON ではない、プレイブックではない、チェックがない、またはチェックが 100 件を超えている（ライブラリが保持できる上限）。あるいは、どのチェックも評価できないクエリがある場合。チェックは実行されませんでした
3	少なくとも 1 つのチェックに失敗しました
4	失敗したチェックはありませんが、判定不能または実行できないチェックがありました

複数のファイルがある場合は、対処の優先度が最も高いステータスが返されます。優先順位は 3、1、4 の順です。判定不能には専用のステータスがあるため、パイプラインで意図的に許容できます（… || test $? -eq 4）。

GitHub Actions では、--format github を指定すると、テキストレポートの後にアノテーションが追加されます。合格しなかった各チェックについてプレイブックにアノテーションが付けられ、判定不能の場合は警告、それ以外の場合はエラーになります。また、チェックできなかった各ファイル、または無効なプレイブックにエラーが付けられます。

jobs:
  checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      # … the steps that write out/orders.json
      - run: npx -y jsonloupe@^1.8.0 check carrier-dumps.playbook.json out/orders.json --format github

エージェントは、プレイブックのパスまたはインラインのチェックを指定して、MCP サーバーの run_checks（以下を参照）から同じゲートを実行できます。有効な JSON ではないドキュメントは同じ方法で拒否されます。allowRepair: true を指定すると、修復後のドキュメントをチェックし、その旨が示されます。

AI エージェントでの使用

同じエンジンがMCPサーバーとしても動作するため、 エージェントはコンテキストに収まらないドキュメントも扱えます。

claude mcp add jsonloupe -- npx -y -p jsonloupe jsonloupe-mcp

jq と通常の JSON が使える場合は、jq を使用してください。 この機能は、jq では扱いにくいケース向けです。まずデコードする必要がある圧縮ペイロード（.zst、Base64-Zstd、PostgreSQL の \x… bytea）、パイプライン全体を通して正確に保持しなければならない int64 と小数の桁、2 つのドキュメント間で ID キーを使用して行うセマンティック差分、そして jq を実行するシェルがない MCP ホストが該当します。

12 個のツール（1.8 から run_checks を追加）：load_doc、get_schema、run_query、profile、sample、diff_docs、export_csv、export_result に加え、上記のスプレッドシート処理向けの inspect、draft_spec、convert、そしてドキュメントを プレイブックのチェックに照らして判定し、その関数は決して実行しない run_checks です。質問が 1 つの場合は、filePath を get_schema、run_query、profile、sample、export_csv、export_result、または run_checks に直接渡してください。ドキュメントを開き、同じ呼び出し内で再利用可能な docId を返します。複数の質問を続けて行う場合、および docId を受け取る diff_docs とコンバーターツールを使う場合は、load_doc を一度呼び出し、その docId を再利用してください。最大 8 つのドキュメントを開いたままにできます。それを超えると、最も長く使われていないドキュメントが閉じられ、次の応答でその旨が通知されます。クエリの詳細は既定で 10 行です（概要のみの場合は limit=0、ページ分けする場合は offset と limit を使用してください）。テキストと構造化 MCP 結果の両方に上限が設定されています。37 MB のルーティングペイロードでの典型的な実行例：

run_query filePath=payload.json "$.tasks[?(@.status == 'FAILED')] | count"
                                  → docId: d1 · count: 17500
profile d1 "$.tasks[*]"          → auto-discovered field coverage, null/missing/types,
                                    exact sums/stats, lengths, distincts and top values
run_query d1 "$.tasks[?(@.status == 'FAILED')] | group(@.region, @.failureReason)"
                                  → composite breakdown, exact complete counts
run_query d1 "$.tasks[*] | top(@.delayMinutes, @.id, @.status)" limit=5
                                  → only the five highest rows; the full array never enters context
sample d1 "$.tasks[0]"           → the whole element, id 9007199254740993 intact
export_result d1 "…| pluck(@.id, @.failureReason)" format=csv outPath=failed.csv
                                  → complete, atomic, rows + UTF-8 bytes only
inspect d1                       → candidate tables, fields, types, deterministic suggestions
draft_spec d1 outPath=tasks.spec.json
                                  → reviewable mapping on disk
convert d1 specPath=tasks.spec.json outPath=tasks.xlsx
                                  → workbook path + row/skipped/warning counts, never its rows
run_checks d1 playbookPath=tasks.playbook.json
                                  → pass, fail or inconclusive per check (or could not run);
                                    a failed or inconclusive check names its first paths
                                    ($.tasks[3]); functions counted, never run

一般的なスキーマ → プロファイル → クエリのループは、JSON を読み込んだり、その場限りの Python スクリプトを書いたりするよりも、意図的に低コストで実行できます。件数や集計値は、結果リストをメモリ上に作成せず、すべての一致項目をストリーミング処理して算出します。present、missing、isNull により、false、null、不在を区別できます。複合グループ化と上限付きの top／bottom により、ローカルでソートするスクリプトは不要です。さらに、プロファイルでは 1 回のスキャンで複数のフィールド、または自動検出したフィールドを調べられます。完全な CSV／JSONL エクスポートは一時ファイルにストリーミング出力され、アトミックに公開されます。エージェントが overwrite=true を明示的に指定しない限り、既存のパスへの出力は拒否されます。

サーバーはネットワーク呼び出しを行わず、明示的に指定された入出力パスのみを使用します。クエリが不正な場合は、空の結果ではなく、文法と修正案を返します。再現可能なエージェント選択評価では、Python も利用できる状況でエージェントがこれらの操作を選ぶかどうかを測定します。

エージェントが MCP のインストールを認識しているのに、その場限りのスクリプトを書き続ける場合は、このルーティングルールをプロジェクトの指示に記載してください（例：AGENTS.md または CLAUDE.md）。

小規模で通常の JSON には、すでに最も簡潔で安全な選択肢である場合、jq を使用してください。 それ以外の場合、JsonLoupe がその操作に対応しているなら、場当たり的な Python より JsonLoupe MCP を優先してください。その操作に JsonLoupe で対応できない場合に限り、独自のシェルコードを使用してください。

ブラウザー内：WebMCP

ブラウザーがWebMCP （document.modelContext — Chrome 149 からの Chrome オリジントライアル、および ChatGPT デスクトップアプリ内蔵ブラウザー）を公開している環境では、jsonloupe.dev が、すでに画面に表示されているドキュメントを対象に、同じ上限付きの動詞を登録します。これにより、ブラウザーエージェントと画面を見ている人がコピーをやり取りせずに、同じドキュメントを共有できます。ツールは 8 個です。run_query、get_schema、profile、sample は stdio 経由の場合と同様に動作します。残りの 4 つはビューアー自体を操作します。ヘッドレスサーバーではできない操作です。load_doc はビューアー内でドキュメントを開き、reveal_path はツリーをスクロールして行を表示し、点滅させます。また、highlight_matches／clear_highlights はツールバー独自のフィルター状態を操作します。フィルターは画面上に表示され、件数が示され、人が専用ボタンで解除できます。ドキュメントの内容を返すすべてのツールには untrustedContentHint の注釈が付いています。値はデータであり、指示ではありません。この API に対応していないブラウザーは何も取得せず、従来どおり同じアプリを実行します。詳細、テスト手順、出典については WEBMCP.mdを参照してください。

プライバシーとセキュリティ

ドキュメントがマシンの外に送信されることはありません。ネットワーク呼び出しの全一覧（4 回の fetch 呼び出し。いずれもオプトインのモデル接続または英語クエリの翻訳で使用）、LLM の形状のみを扱う契約、および XSS 対策については、SECURITY.md に記載されています。対応する 脅威モデル、信頼境界、および保証に関する論拠については、 SECURITY-ASSURANCE.md に記載されています。

デプロイ

jsonloupe は完全な静的サイトとしてビルドされます。

npm run build      # dist/

dist/ を任意の静的ホスト（GitHub Pages、Cloudflare Pages、Netlify など）から配信してください。 アプリの動作にサーバーサイドの機能は必要ありません。jsonloupe.dev と同等の 保護を実現するには、ホストで SECURITY-HEADERS.md に記載されたレスポンスヘッダーを設定してください。特に /assets/run-sandbox-*.js に対する Run サンドボックス独自の CSP は必須です。これがないと、貼り付けられたスクリプトの import() があらゆるホストにアクセスできてしまいます。ローカルの /__api-key 便利エンドポイント（開発モード、または npx jsonloupe --key-file）は静的デプロイには 存在せず、英語翻訳は訪問者が自身のモデルアカウントまたはキーを接続した場合にのみ有効になります。

開発

npm run dev        # Vite on :5199, with the loopback-only /__api-key endpoint
npm test           # vitest — engine, worker, converter, playbook, CLI, MCP, WebMCP, NL and DOM suites
npm run lint:security  # FLOSS security analysis + checked TypeScript style
npm run lint:contract  # the UI contract in src/style.css: tokens, contrast, motion, type ramp
npm run lint:headers   # every source file carries the MIT SPDX and copyright notice
npm run coverage   # same suite with enforced 90% statement / 80% branch floors
npm run build      # type checks + vite build + the MCP and CLI bundles
npm run build:mcp  # or build:cli — one target's type check and bundle only
npm run test:a11y  # real Chromium: axe, keyboard/focus, playbook and WebMCP journeys (run after build)
npm run check:site-headers # verify the live OpenSSF hardening headers
npm run check:reproducible-build  # clean locked installs must produce identical bytes
npm run smoke:mcp  # drives the built MCP server over real stdio against a 37 MB fixture (run after build)
npm run eval:agent -- --help  # black-box MCP-vs-Python agent-choice benchmark
npm run eval:ask -- --dry-run  # Ask correctness/injection suite; --dry-run costs nothing

まずは CONTRIBUTING.md をご覧ください。アーキテクチャと内部構造は ARCHITECTURE.md および SPEC.md に記載されています。コンバーターには独自の SPEC-converter.md があり、意図的に対応していない内容も説明されています。プロジェクトの決定事項と今後 12 か月の計画は、GOVERNANCE.md および ROADMAP.md に記載されています。公式リリースと利用者による検証については、RELEASING.md をご覧ください。各リリースでの変更点は CHANGELOG.md に記載されています。

ライセンス

MIT。同梱されているサードパーティパッケージの一覧は THIRD_PARTY_LICENSES.md にあります。

ソフトウェアは「現状のまま」提供され、いかなる種類の保証もありません。詳しくはライセンス 本文をご覧ください。英語クエリのためにモデルを接続した場合、設定した LLM プロバイダーの利用には、そのプロバイダーの利用規約が適用されます。