Json MCP Filter

🚀 JSON MCP過濾器

JSON MCP過濾器是一款強大的模型上下文協議（MCP）服務器，它為本地文件和遠程HTTP/HTTPS端點提供JSON模式生成和過濾工具。該工具藉助quicktype實現強大的TypeScript類型生成功能。

適用場景：過濾大型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進行預下載檢查
• 內存安全，防止內存溢出錯誤
• 清晰的錯誤消息，顯示實際大小與限制大小

最佳實踐

• 對於大型文件，先使用json_dry_run
• 在生成模式之前使用json_filter進行過濾
• 僅關注必要字段的形狀

🌐 支持的數據源

• 公共API - 具有JSON響應的REST端點
• 靜態文件 - 網絡服務器上的JSON文件
• 本地開發 - 開發期間的http://localhost
• 本地文件 - 文件系統訪問

💡 常見工作流程

LLM集成：

1. API返回大型響應
2. json_filter提取相關字段
3. 處理無噪音的乾淨數據
4. json_schema生成類型以確保安全性