JSON Skeleton

You can run a lightweight MCP server that generates compact skeleton representations of large JSON files. It preserves structure while truncating string values and can operate in a type-only mode to reveal data types, making it ideal for quickly understanding JSON layouts without transferring full data payloads.

How to use

Use an MCP client to connect to the JSON Skeleton MCP server. You can run the server locally or via a remote runtime, then point your MCP client to its command and arguments. The server exposes a tool named json_skeleton that processes a JSON file and returns a truncated skeleton or a type-only skeleton for quick structure discovery.

Configure your MCP client to load the json_skeleton server with one of the provided runtime configurations. The primary options are a remote runtime using uvx from a git source or a local runtime using uvx with a local path. These configurations tell your client how to start the server and what identifier to use in your workflow.

How to install

prerequisites: Python 3.10+ and uvx must be available on your system to run the MCP server, along with Git to fetch remote sources.

Install via the quick start method using uvx to run the MCP server from a git source or a local path.

# 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

Configuration and usage examples

The server provides a tool named json_skeleton with configurable parameters. Use these patterns to process a JSON file and obtain a skeleton with either full strings truncated or only data types shown.

{
  "mcpServers": {
    "json-skeleton": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jskorlol/json-skeleton-mcp.git", "json-skeleton"]
    }
  }
}

Examples of how to use the json_skeleton tool

Basic usage shows a standard skeleton where strings are truncated to the default maximum length (200 characters).

Custom string length lets you control how aggressively values are shortened.

Type-only mode returns only the data types, which is the most compact representation.

# Basic usage
{"file_path": "/path/to/data.json"}

# Custom string length
{"file_path": "/path/to/data.json", "max_length": 50}

# Type-only mode
{"file_path": "/path/to/data.json", "type_only": true}

Programmatic usage

If you are using the Python interface, you can initialize the generator and process a file to obtain the skeleton in code.

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 and practical notes

Array deduplication keeps unique structures within arrays, presenting a representative set of shapes without duplicating identical DTOs. In type-only mode, array elements are shown by their type rather than values.

Value processing maintains numbers, booleans, and nulls in normal mode, while truncating long strings with a clear suffix to indicate truncation. Type-only mode replaces all values with their type names (str, int, float, bool, null).

Available tools

json_skeleton

Creates a lightweight skeleton of a JSON file with configurable max string length and an option for type-only output. It handles arrays with deduplication by DTO structure and truncates string values in normal mode while preserving numeric and boolean values.