Json Skeleton MCP

🚀 JSON骨架MCP服务器

JSON骨架MCP服务器是一个轻量级的MCP（模型上下文协议）服务器，它能为大型JSON文件创建紧凑的“骨架”表示，帮助你在无需处理完整数据负载的情况下理解JSON结构。

🚀 快速开始

JSON骨架MCP服务器可以帮助你在不处理完整数据的情况下理解JSON文件的结构。以下是使用该服务器的快速指南。

✨ 主要特性

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

📦 安装指南

使用uvx快速启动（推荐）

你可以使用uvx直接运行MCP服务器，而无需安装：

# 从GitHub运行
uvx --from git+https://github.com/jskorlol/json-skeleton-mcp.git json-skeleton

# 从本地目录运行
uvx --from /path/to/json-skeleton-mcp json-skeleton

传统安装方式

1. 克隆此仓库：

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

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

python -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate
pip install -e .

💻 使用示例

在Claude桌面版中作为MCP服务器使用

添加到你的Claude桌面版配置中：

使用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：基础用法

输入: json_skeleton(file_path="/path/to/data.json")
输出: 字符串限制为200个字符的截断JSON

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

输入: json_skeleton(file_path="/path/to/data.json", max_length=50)
输出: 更激进截断的JSON，字符串限制为50个字符

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

输入: json_skeleton(file_path="/path/to/data.json", type_only=true)
输出: 
{
  "name": "str",
  "age": "int",
  "active": "bool",
  "balance": "float",
  "notes": "null",
  "items": [
    {
      "id": "int",
      "label": "str"
    }
  ]
}

编程式用法

from json_skeleton import SkeletonGenerator

# 初始化生成器
generator = SkeletonGenerator(max_value_length=200)

# 处理文件
result = generator.process_file("large_data.json")
print(result['skeleton'])

# 使用自定义长度处理
result = generator.process_file("large_data.json", max_length=50)
print(result['skeleton'])

# 在仅显示类型模式下处理
result = generator.process_file("large_data.json", type_only=True)
print(result['skeleton'])

# 或者直接处理数据
data = {"key": "very long value" * 50, "items": [1, 2, 3, 1, 2, 3]}
skeleton = generator.create_skeleton(data)
print(skeleton)

🔧 技术细节

数组去重

该工具通过比较数组项的DTO（数据传输对象）结构来智能地去重：

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

值处理

• 正常模式：长度超过max_length的字符串会被截断，并添加“...(truncated)”后缀。
• 仅显示类型模式：所有值都替换为其类型名称（str、int、float、bool、null）。
• 在正常模式下，数字、布尔值和空值保持不变。

📚 详细文档

使用场景

1. 理解API响应：快速掌握大型API响应的结构，无需处理数兆字节的数据。
2. 文档编写：为API文档生成结构示例。
3. 开发工作：处理数据结构，而无需处理大负载。
4. 令牌优化：在使用AI模型时减少令牌使用。
5. 模式发现：使用仅显示类型模式来理解复杂JSON结构中的数据类型。

测试

运行测试脚本来查看工具的实际效果：

# 测试基本功能
python test_skeleton.py

# 测试不同的max_length值
python test_max_length.py

# 测试仅显示类型模式
python test_type_only.py

要求

• Python 3.10+
• MCP库

📄 许可证

本项目采用MIT许可证。