JSON Skeleton MCP Server

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

Related MCP server: JSON MCP Server

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

Clone this repository:

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

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

Understanding API Responses: Quickly grasp the structure of large API responses without processing megabytes of data
Documentation: Generate structure examples for API documentation
Development: Work with data structure without handling large payloads
Token Optimization: Reduce token usage when working with AI models
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

JSON Skeleton MCP Server

JSON Skeleton MCP Server

Features

Installation

Quick Start with uvx (Recommended)

Traditional Installation

Usage

As MCP Server in Claude Desktop

Available Tool

Example 1: Basic Usage

Example 2: Custom String Length

Example 3: Type-Only Mode (Most Compact)

Programmatic Usage

How It Works

Array Deduplication

Value Processing

Use Cases

Testing

Requirements

License

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API