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

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

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

json_skeleton

Creates compact skeleton representations of large JSON files by preserving structure while truncating string values and deduplicating arrays, helping users understand JSON structure without processing the full data payload.

Related MCP Servers

Divide and Conquer MCP Server
landicefu
A
security
A
license
A
quality
Enables AI agents to break down complex tasks into manageable pieces using a structured JSON format with task tracking, context preservation, and progress monitoring capabilities.
Last updated -
15
150
6
MIT License
JSON MCP Server
berrydev-ai
-
security
F
license
-
quality
Provides powerful JSON manipulation tools through Model Context Protocol, enabling complex queries, schema generation, and validation with jq notation and native Node.js operations.
Last updated -
4
JSON MCP Server
kehvinbehvin
A
security
A
license
A
quality
Provides JSON schema generation and filtering tools for LLMs, helping with large JSON files by converting them to TypeScript definitions and extracting specific fields to reduce context size.
Last updated -
3
15
10
MIT License
Fetch JSONPath MCP
ackness
A
security
F
license
A
quality
Enables efficient extraction of specific data from JSON APIs using JSONPath patterns, reducing token usage by up to 99% compared to fetching entire responses. Supports single and batch operations for both JSON extraction and raw text retrieval from URLs.
Last updated -
4
1

View all related MCP servers

JSON Skeleton MCP Server