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"]
}
}
}
json_skeleton
Creates a lightweight skeleton of a JSON file with the following parameters:
file_path (required): Path to the JSON file to processmax_length (optional, default: 200): Maximum length for string valuestype_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
License
MIT License