Json Skeleton MCP

🚀 JSON Skeleton MCP Server

A lightweight MCP (Model Context Protocol) server that creates compact "skeleton" representations of large JSON files. It helps you understand the JSON structure without dealing with the full data payload.

🚀 Quick Start

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

1. Clone this repository:

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

2. Create a virtual environment and install:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

✨ Features

• Lightweight JSON Skeleton: Preserves the structure with truncated string values.
• Configurable String Length: Allows you to customize the maximum string length (default: 200 chars).
• Type-Only Mode: Provides an ultra-compact output showing only data types.
• Smart Array Deduplication: Keeps only unique DTO structures in arrays.
• Efficient Processing: Can handle massive JSON files that exceed AI model context limits.

📦 Installation

The installation methods are described in the "Quick Start" section above.

💻 Usage Examples

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).

Basic Usage

Input: json_skeleton(file_path="/path/to/data.json")
Output: Truncated JSON with strings limited to 200 characters

Custom String Length

Input: json_skeleton(file_path="/path/to/data.json", max_length=50)
Output: More aggressively truncated JSON with 50-char limit

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)

🔧 Technical Details

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 are replaced with their type names (str, int, float, bool, null).
• Numbers, booleans, and nulls are preserved as-is in normal mode.

📚 Documentation

Use Cases

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