json-mcp过滤器

Name: json-mcp过滤器
Author: kehvinbehvin

作者：kehvinbehvin17 星标更新：2025-10-23

安装使用来源：spider==github.com

项目介绍

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错误，形状过滤问题

所有错误都包含可操作的调试信息。

⚡ 性能

处理时间

文件大小	处理时间
< 100 KB	< 10ms
1-10 MB	100ms - 1s
10-50 MB	1s - 5s
> 50 MB	阻止

大小保护

50MB最大限制适用于所有来源
预下载检查通过Content-Length
内存安全防止OOM错误
清晰的错误消息显示实际大小与限制大小

最佳实践

对于大型文件，首先使用json_dry_run
在模式生成前使用json_filter进行过滤
将形状集中在关键字段上

🌐 支持的数据源

公共API - 返回JSON响应的REST端点
静态文件 - 网站服务器上的JSON文件
本地开发 - 开发期间的http://localhost
本地文件 - 文件系统访问

💡 常见工作流

LLM集成：

API返回大量响应
json_filter提取相关字段
处理干净数据，去除噪音
json_schema生成类型以保证安全