JSON Skeleton

A lightweight MCP (Model Context Protocol) server that creates compact "skeleton" representations of large JSON files, helping you understand JSON structure without the full data payload.

Features

• Lightweight JSON Skeleton: Preserves structure with truncated string values
• Configurable String Length: Customize max string length (default: 200 chars)
• Type-Only Mode: Ultra-compact output showing only data types
• Smart Array Deduplication: Keeps only unique DTO structures in arrays
• Efficient Processing: Handles massive JSON files that exceed AI model context limits

Installation

Quick Start with uvx (Recommended)

You can run the MCP server directly without installation using uvx:

# Run from GitHub
uvx --from git+https://github.com/jskorlol/json-skeleton-mcp.git json-skeleton

# Run from local directory
uvx --from /path/to/json-skeleton-mcp json-skeleton

Traditional Installation

1. Clone this repository:

git clone https://github.com/jskorlol/json-skeleton-mcp.git
cd json-skeleton-mcp

2. Create a virtual environment and install:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Usage

As MCP Server in Claude Desktop

Add to your Claude Desktop configuration:

Using uvx (Recommended):

{
  "mcpServers": {
    "json-skeleton": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jskorlol/json-skeleton-mcp.git", "json-skeleton"]
    }
  }
}

Using local installation:

{
  "mcpServers": {
    "json-skeleton": {
      "command": "uvx",
      "args": ["--from", "/path/to/json-skeleton-mcp", "json-skeleton"]
    }
  }
}

Available Tool

json_skeleton

Creates a lightweight skeleton of a JSON file with the following parameters:

• file_path (required): Path to the JSON file to process
• max_length (optional, default: 200): Maximum length for string values
• type_only (optional, default: false): Return only value types instead of values (most compact output)

Example 1: Basic Usage

Input: json_skeleton(file_path="/path/to/data.json")
Output: Truncated JSON with strings limited to 200 characters

Example 2: Custom String Length

Input: json_skeleton(file_path="/path/to/data.json", max_length=50)
Output: More aggressively truncated JSON with 50-char limit

Example 3: Type-Only Mode (Most Compact)

Input: json_skeleton(file_path="/path/to/data.json", type_only=true)
Output: 
{
  "name": "str",
  "age": "int",
  "active": "bool",
  "balance": "float",
  "notes": "null",
  "items": [
    {
      "id": "int",
      "label": "str"
    }
  ]
}

Programmatic Usage

from json_skeleton import SkeletonGenerator

# Initialize generator
generator = SkeletonGenerator(max_value_length=200)

# Process a file
result = generator.process_file("large_data.json")
print(result['skeleton'])

# Process with custom length
result = generator.process_file("large_data.json", max_length=50)
print(result['skeleton'])

# Process in type-only mode
result = generator.process_file("large_data.json", type_only=True)
print(result['skeleton'])

# Or process data directly
data = {"key": "very long value" * 50, "items": [1, 2, 3, 1, 2, 3]}
skeleton = generator.create_skeleton(data)
print(skeleton)

How It Works

Array Deduplication

The tool intelligently deduplicates array items by comparing their DTO (Data Transfer Object) structure:

• For primitive arrays: Keeps up to 3 unique values
• For object arrays: Keeps one example of each unique structure
• Structure comparison is based on keys and value types, not actual values
• In type-only mode: Shows only the type of the first array element

Value Processing

• Normal Mode: Strings longer than max_length are truncated with "...(truncated)" suffix
• Type-Only Mode: All values replaced with their type names (str, int, float, bool, null)
• Numbers, booleans, and nulls are preserved as-is in normal mode

Use Cases

1. Understanding API Responses: Quickly grasp the structure of large API responses without processing megabytes of data
2. Documentation: Generate structure examples for API documentation
3. Development: Work with data structure without handling large payloads
4. Token Optimization: Reduce token usage when working with AI models
5. Schema Discovery: Use type-only mode to understand data types in complex JSON structures

Testing

Run the test scripts to see the tool in action:

# Test basic functionality
python test_skeleton.py

# Test with different max_length values
python test_max_length.py

# Test type-only mode
python test_type_only.py

Requirements

• Python 3.10+
• MCP library

License

MIT License