JSON Skeleton MCP Server

JSON骨架MCP服务器

一个轻量级的MCP（模型上下文协议）服务器，可以创建大型JSON文件的紧凑“骨架”表示，帮助您在没有完整数据负载的情况下理解JSON结构。

特性

• 轻量级JSON骨架：保留截断字符串值的结构
• 可配置字符串长度：自定义最大字符串长度（默认值：200个字符）
• 仅类型模式：超紧凑输出，仅显示数据类型
• 智能阵列重复数据消除：在数组中仅保留唯一的DTO结构
• 有效处理：处理超过AI模型上下文限制的大量JSON文件

安装

uvx快速入门（推荐）

您可以使用直接运行MCP服务器，而无需安装 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

传统安装

1. 克隆此存储库：

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

1. 创建虚拟环境并安装：

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

用法

作为Claude Desktop中的MCP服务器

添加到您的Claude Desktop配置中：

使用uvx（推荐）：

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

使用本地安装：

{
  "mcpServers": {
    "json-skeleton": {
      "command": "uvx",
      "args": ["--from", "/path/to/json-skeleton-mcp", "json-skeleton"]
    }
  }
}

可用工具

json_skeleton

使用以下参数创建JSON文件的轻量级骨架：

• file_path （必填）：要处理的JSON文件的路径
• max_length （可选，默认值：200）：字符串值的最大长度
• type_only （可选，默认值：false）：仅返回值类型而不是值（最紧凑的输出）

示例1：基本用法

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

示例2：自定义字符串长度

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

示例3：仅类型模式（最紧凑型）

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"
    }
  ]
}

程序化使用

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)

运作原理

阵列重复数据消除

该工具通过比较阵列项的DTO（数据传输对象）结构来智能地消除重复：

• 对于原始数组：最多保留3个唯一值
• 对于对象数组：保留每个唯一结构的一个示例
• 结构比较基于键和值类型，而不是实际值
• 在仅类型模式下：仅显示第一个数组元素的类型

价值处理

• 正常模式：长度超过max_length的字符串将使用“…（截断）”后缀截断
• 仅类型模式：所有值都替换为它们的类型名称（str、int、float、bool、null）
• 数字、布尔值和空值在正常模式下保持不变

用例

1. 了解API响应：快速掌握大型API响应的结构，无需处理兆字节的数据
2. 文档：生成API文档的结构示例
3. 发展：在不处理大型有效载荷的情况下使用数据结构
4. 令牌优化：使用AI模型时减少令牌使用
5. 架构发现：使用纯类型模式来理解复杂JSON结构中的数据类型

测试

运行测试脚本以查看工具的运行情况：

# 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

需求

• Python 3.10+
• MCP库

许可证

MIT许可证