Json MCP Filter

最適な用途: 大規模なJSONファイルやAPIレスポンスをフィルタリングし、LLMコンテキストに関連するデータのみを抽出し、型安全性を維持します。

✨ 主な機能

• 🔄 スキーマ生成 - quicktypeを使用してJSONをTypeScriptインターフェースに変換します
• 🎯 スマートフィルタリング - 形状ベースのフィルタリングで特定のフィールドを抽出します
• 🌐 リモートサポート - HTTP/HTTPSのURLやAPIエンドポイントで動作します
• 📦 自動チャンク化 - 400KBの自動チャンク化で大規模なデータセットを処理します
• 🛡️ サイズ保護 - 50MBの制限とメモリ安全性が組み込まれています
• ⚡ MCP対応 - Claude DesktopとClaude Codeとのシームレスな統合が可能です
• 🚨 スマートエラー - デバッグ情報付きの明確で実行可能なエラーメッセージを提供します

🛠️ 利用可能なツール

json_schema

JSONデータからTypeScriptインターフェースを生成します。

パラメータ:

• filePath: ローカルファイルパスまたはHTTP/HTTPSのURL

例:

// 入力JSON
{"name": "John", "age": 30, "city": "New York"}

// 生成されたTypeScript
export interface GeneratedType {
    name: string;
    age:  number;
    city: string;
}

json_filter

形状ベースのフィルタリングを使用して特定のフィールドを抽出し、大規模なデータセットに対して自動チャンク化を行います。

パラメータ:

• filePath: ローカルファイルパスまたはHTTP/HTTPSのURL
• shape: 抽出するフィールドを定義するオブジェクト
• chunkIndex (オプション): 大規模なデータセットのチャンクインデックス (0から始まる)

自動チャンク化:

• ≤400KB: すべてのデータを返します

• 400KB: メタデータ付きで自動チャンク化します

json_dry_run

フィルタリング前にデータサイズを分析し、チャンク化の推奨事項を提供します。

パラメータ:

• filePath: ローカルファイルパスまたはHTTP/HTTPSのURL
• shape: 分析する内容を定義するオブジェクト

返り値: サイズの内訳とチャンクの推奨事項

💻 使用例

基本的なフィルタリング

// 単純なフィールド抽出
json_filter({
  filePath: "https://api.example.com/users",
  shape: {"name": true, "email": true}
})

形状パターン

// 単一フィールド
{"name": true}

// ネストされたオブジェクト
{"user": {"name": true, "email": true}}

// 配列 (各アイテムに適用)
{"users": {"name": true, "age": true}}

// 複雑なネスト
{
  "results": {
    "profile": {"name": true, "location": {"city": true}}
  }
}

大規模データセットのワークフロー

// 1. まずサイズを確認
json_dry_run({filePath: "./large.json", shape: {"users": {"id": true}}})
// → "推奨チャンク数: 6"

// 2. チャンクを取得
json_filter({filePath: "./large.json", shape: {"users": {"id": true}}})
// → チャンク0 + メタデータ

json_filter({filePath: "./large.json", shape: {"users": {"id": true}}, chunkIndex: 1})
// → チャンク1 + メタデータ

🔒 セキュリティに関する注意

リモートデータの取得: このツールはHTTP/HTTPSのURLからデータを取得します。ユーザーは以下のことを責任負って行う必要があります。

✅ 安全な実践:

• URLが正当なエンドポイントを指していることを確認する
• 信頼できる公開APIのみを使用する
• APIのレート制限とサービス利用規約を尊重する
• データソースを処理する前に確認する

❌ メンテナーは以下のことに責任を負いません:

• 外部URLの内容
• リモートリクエストのプライバシーへの影響
• サードパーティAPIの乱用や違反

💡 推奨事項: 信頼できる公開データソースのみを使用してください。

🚀 クイックスタート

オプション1: NPX (推奨)

# インストール不要
npx json-mcp-filter@latest

オプション2: グローバルインストール

npm install -g json-mcp-filter@latest
json-mcp-server

オプション3: ソースから

git clone <repository-url>
cd json-mcp-filter
npm install
npm run build

🔧 MCP統合

Claude Desktop

設定ファイルに追加します:

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

Claude Code

# CLIを通じて追加
claude mcp add json-mcp-filter npx -y json-mcp-filter@latest

または手動で追加します:

• 名前: json-mcp-filter
• コマンド: npx
• 引数: ["-y", "json-mcp-filter@latest"]

🔧 開発

コマンド

npm run build      # TypeScriptをコンパイル
npm run start      # コンパイルされたサーバーを実行
npm run inspect    # MCPインスペクターでデバッグ
npx tsc --noEmit   # 型チェックのみ

テスト

npm run inspect    # 対話型テストインターフェース

📁 プロジェクト構造

src/
├── index.ts                    # メインサーバー + ツール
├── strategies/                 # データ取り込み戦略
│   ├── JsonIngestionStrategy.ts  # 抽象インターフェース
│   ├── LocalFileStrategy.ts      # ローカルファイルアクセス
│   └── HttpJsonStrategy.ts       # HTTP/HTTPSのデータ取得
├── context/
│   └── JsonIngestionContext.ts   # 戦略管理
└── types/
    └── JsonIngestion.ts          # 型定義

🚨 エラーハンドリング

包括的なカバレッジ

• ローカルファイル: ファイルが見つからない、パーミッションエラー、無効なJSON
• リモートURL: ネットワークエラー、認証エラー (401/403)、サーバーエラー (500以上)
• コンテンツサイズ: 50MBを超える場合は自動的に拒否し、明確なメッセージを表示
• 形式検出: HTML/XMLのスマート検出とガイダンス
• レート制限: 429レスポンスとリトライ指示
• 処理: quicktypeエラー、形状フィルタリングの問題

すべてのエラーには実行可能なデバッグ情報が含まれています。

⚡ パフォーマンス

処理時間

サイズ保護

• すべてのソースに対して最大50MB
• Content-Lengthを使用したダウンロード前のチェック
• メモリ安全性によりOOMエラーを防止
• 実際のサイズと制限サイズを含む明確なエラーメッセージ

ベストプラクティス

• 大きなファイルの場合は最初にjson_dry_runを使用する
• スキーマ生成前にjson_filterでフィルタリングする
• 形状を必須のフィールドのみに絞る

🌐 サポートされるデータソース

• 公開API - JSONレスポンスを返すRESTエンドポイント
• 静的ファイル - Webサーバー上のJSONファイル
• ローカル開発 - 開発中のhttp://localhost
• ローカルファイル - ファイルシステムへのアクセス

💡 一般的なワークフロー

LLM統合:

1. APIが大きなレスポンスを返す
2. json_filterで関連するフィールドを抽出する
3. ノイズのないクリーンなデータを処理する
4. json_schemaで型を生成して安全性を確保する