README.md•4.85 kB
# 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`:
```bash
# 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:
```bash
git clone https://github.com/jskorlol/json-skeleton-mcp.git
cd json-skeleton-mcp
```
2. Create a virtual environment and install:
```bash
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):**
```json
{
"mcpServers": {
"json-skeleton": {
"command": "uvx",
"args": ["--from", "git+https://github.com/jskorlol/json-skeleton-mcp.git", "json-skeleton"]
}
}
}
```
**Using local installation:**
```json
{
"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)
#### 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
```python
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
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:
```bash
# 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