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
Metadata
Release files for iflow-mcp_json-skeleton-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_json_skeleton_mcp-0.1.0.tar.gz | 8.5 kB | Without provenance | Details for iflow_mcp_json_skeleton_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_json_skeleton_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_json_skeleton_mcp-0.1.0-py3-none-any.whl |
Total release size: 15.5 kB
Release files / iflow_mcp_json_skeleton_mcp-0.1.0.tar.gz
| Download URL | iflow_mcp_json_skeleton_mcp-0.1.0.tar.gz |
|---|---|
| Size | 8.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0170ba7148ba98343faa2167e23ff73f553d01968adc74d5b1374b72db4b2fb9
|
|
BLAKE2b-256 checksum How to use checksums |
e9c6af1e530d3eedfb05a1b0888192adf63a7e0e3f5574d73fadf16af38f54e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.9
|
Release files / iflow_mcp_json_skeleton_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_json_skeleton_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 6.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b8ae37b825078382b4cacd287f5d2d5de04c5ab44f3bbfe8caaa74e88e06d18
|
|
BLAKE2b-256 checksum How to use checksums |
debbb59742f06c27bf1318c3c328e757fe23d527717e54eb538d2d76552f5f50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.9
|
Security for iflow-mcp_json-skeleton-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.