# 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