Json Mcp Filter

开发 TypeScript

🚀 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 
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进行预下载检查
内存安全，防止内存溢出错误
清晰的错误消息，显示实际大小与限制大小

最佳实践

对于大型文件，先使用json_dry_run
在生成模式之前使用json_filter进行过滤
仅关注必要字段的形状

🌐 支持的数据源

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

💡 常见工作流程

LLM集成：

API返回大型响应
json_filter提取相关字段
处理无噪音的干净数据
json_schema生成类型以确保安全性

0 条评论
分类：开发