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生成类型以确保安全性