A
securityA
licenseA
qualityEnables 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
17
6
MIT License
Enables running the MCP server directly from the GitHub repository without installation using the uvx command.
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 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
Python 3.10+
MCP library
License
MIT License
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
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
- -securityFlicense-qualityProvides 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 -2
- AsecurityAlicenseAqualityProvides 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 -3713MIT License
- AsecurityFlicenseAqualityEnables 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 -41