JSON Analyser

A specialized Model Context Protocol (MCP) server for analyzing large JSON files with memory-efficient streaming capabilities.

Features

• Memory-Efficient Streaming: Process gigabyte-sized JSON files without loading them entirely into memory
• Advanced Querying: Search JSON data with multiple operators and conditions
• Schema Detection: Automatically analyze JSON structure and field types
• Chunk Processing: Iterate through large datasets in manageable chunks
• Multi-Field Queries: Complex queries with AND logic across multiple fields
• Unique Value Analysis: Extract unique values for any field
• Performance Tracking: Monitor processing times and memory usage

Installation

npm install -g json-analyser-mcp

Usage

As MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "JSON Analyser MCP": {
      "command": "npx",
      "args": ["-y", "json-analyser-mcp", "--stdio"]
    }
  }
}

Available Tools

1. read_json

Get an overview and preview of a JSON file.

{
  "filePath": "path/to/data.json",
  "fields": ["field1", "field2"], // optional
  "detectSchema": true // optional, analyzes field types
}

2. query_json

Search for specific data with various operators.

{
  "filePath": "path/to/data.json",
  "query": {
    "field": "trading_symbol",
    "operator": "contains", // contains, equals, startsWith, endsWith, regex, gt, lt, gte, lte
    "value": "TITAN",
    "caseSensitive": false // optional
  },
  "maxResults": 1000 // optional
}

3. get_json_chunk

Process JSON data in sequential chunks.

{
  "filePath": "path/to/data.json",
  "fields": ["field1", "field2"], // optional
  "start": 0,
  "limit": 1000
}

4. multi_query_json

Execute multiple queries with AND logic.

{
  "filePath": "path/to/data.json",
  "queries": [
    {
      "field": "category",
      "operator": "equals",
      "value": "technology"
    },
    {
      "field": "price",
      "operator": "gt",
      "value": 100
    }
  ],
  "maxResults": 500
}

5. get_unique_values

Extract unique values for a specific field.

{
  "filePath": "path/to/data.json",
  "field": "category",
  "maxValues": 1000
}

Query Operators

• contains: Field value contains the search string
• equals: Exact match
• startsWith: Field value starts with the search string
• endsWith: Field value ends with the search string
• regex: Regular expression matching
• gt: Greater than (numeric)
• lt: Less than (numeric)
• gte: Greater than or equal (numeric)
• lte: Less than or equal (numeric)

Performance Benefits

• Streaming Architecture: Uses stream-json for memory-efficient processing
• Large File Support: Can handle multi-gigabyte JSON files
• Fast Searches: Optimized for quick data retrieval
• Minimal Memory Footprint: Processes data without loading entire files

Use Cases

• Data Analysis: Explore large datasets without memory constraints
• Log Processing: Search through application logs efficiently
• API Response Analysis: Process large API response files
• Data Migration: Extract and transform data from JSON exports
• Research: Analyze research datasets and survey responses

Example Workflows

Analyzing Trading Data

// 1. First, get an overview
read_json({ filePath: "NSE.json", detectSchema: true })

// 2. Search for specific stocks
query_json({
  filePath: "NSE.json",
  query: { field: "trading_symbol", operator: "contains", value: "TITAN" }
})

// 3. Get unique sectors
get_unique_values({ filePath: "NSE.json", field: "sector" })

Processing Support Tickets

// 1. Get overview
read_json({ filePath: "tickets.json" })

// 2. Find high-priority open tickets
multi_query_json({
  filePath: "tickets.json",
  queries: [
    { field: "status", operator: "equals", value: "open" },
    { field: "priority", operator: "equals", value: "high" }
  ]
})

// 3. Process all tickets in chunks
get_json_chunk({ filePath: "tickets.json", start: 0, limit: 1000 })

Requirements

• Node.js >= 18.0.0
• Memory: Minimal (streams data)
• Disk: Sufficient space for input JSON files

License

MIT

Contributing

Contributions welcome! Please open issues and pull requests on GitHub.

Support

For issues and questions, please use the GitHub issue tracker.