JSON MCP Filter

A powerful Model Context Protocol (MCP) server that provides JSON schema generation and filtering tools for local files and remote HTTP/HTTPS endpoints. Built with quicktype for robust TypeScript type generation.

Perfect for: Filtering large JSON files and API responses to extract only relevant data for LLM context, while maintaining type safety.

✨ Key Features

🔄 Schema Generation - Convert JSON to TypeScript interfaces using quicktype
🎯 Smart Filtering - Extract specific fields with shape-based filtering
🌐 Remote Support - Works with HTTP/HTTPS URLs and API endpoints
📦 Auto Chunking - Handles large datasets with automatic 400KB chunking
🛡️ Size Protection - Built-in 50MB limit with memory safety
⚡ MCP Ready - Seamless integration with Claude Desktop and Claude Code
🚨 Smart Errors - Clear, actionable error messages with debugging info

🛠️ Available Tools

`json_schema`

Generates TypeScript interfaces from JSON data.

Parameters:

filePath: Local file path or HTTP/HTTPS URL

Example:

server.ts

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

// Generated TypeScript
export interface GeneratedType {
    name: string;
    age:  number;
    city: string;
}

`json_filter`

Extracts specific fields using shape-based filtering with automatic chunking for large datasets.

Parameters:

filePath: Local file path or HTTP/HTTPS URL
shape: Object defining which fields to extract
chunkIndex (optional): Chunk index for large datasets (0-based)

Auto-Chunking:

≤400KB: Returns all data
400KB: Auto-chunks with metadata

`json_dry_run`

Analyzes data size and provides chunking recommendations before filtering.

Parameters:

filePath: Local file path or HTTP/HTTPS URL
shape: Object defining what to analyze

Returns: Size breakdown and chunk recommendations

📋 Usage Examples

Basic Filtering

javascript

// Simple field extraction
json_filter({
  filePath: "https://api.example.com/users",
  shape: {"name": true, "email": true}
})

Shape Patterns

javascript

// Single field
{"name": true}

// Nested objects
{"user": {"name": true, "email": true}}

// Arrays (applies to each item)
{"users": {"name": true, "age": true}}

// Complex nested
{
  "results": {
    "profile": {"name": true, "location": {"city": true}}
  }
}

Large Dataset Workflow

javascript

// 1. Check size first
json_dry_run({filePath: "./large.json", shape: {"users": {"id": true}}})
// → "Recommended chunks: 6"

// 2. Get chunks
json_filter({filePath: "./large.json", shape: {"users": {"id": true}}})
// → Chunk 0 + metadata

json_filter({filePath: "./large.json", shape: {"users": {"id": true}}, chunkIndex: 1})
// → Chunk 1 + metadata

🔒 Security Notice

Remote Data Fetching: This tool fetches data from HTTP/HTTPS URLs. Users are responsible for:

✅ Safe Practices:

Verify URLs point to legitimate endpoints
Use trusted, public APIs only
Respect API rate limits and terms of service
Review data sources before processing

❌ Maintainers Not Responsible For:

External URL content
Privacy implications of remote requests
Third-party API abuse or violations

💡 Recommendation: Only use trusted, public data sources.

🚀 Quick Start

Option 1: NPX (Recommended)

bash

# No installation required
npx json-mcp-filter@latest

Option 2: Global Install

Terminal

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

Option 3: From Source

bash

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

⚙️ MCP Integration

Claude Desktop

Add to your configuration file:

config.json

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

Claude Code

bash

# Add via CLI
claude mcp add json-mcp-filter npx -y json-mcp-filter@latest

Or add manually:

Name: json-mcp-filter
Command: npx
Args: ["-y", "json-mcp-filter@latest"]

🔧 Development

Commands

Terminal

npm run build      # Compile TypeScript
npm run start      # Run compiled server  
npm run inspect    # Debug with MCP inspector
npx tsc --noEmit   # Type check only

Testing

Terminal

npm run inspect    # Interactive testing interface

📁 Project Structure

Code

src/
├── index.ts                    # Main server + tools
├── strategies/                 # Data ingestion strategies
│   ├── JsonIngestionStrategy.ts  # Abstract interface
│   ├── LocalFileStrategy.ts      # Local file access
│   └── HttpJsonStrategy.ts       # HTTP/HTTPS fetching
├── context/
│   └── JsonIngestionContext.ts   # Strategy management
└── types/
    └── JsonIngestion.ts          # Type definitions