🚀 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
传统安装方式
- 克隆此仓库：
git clone https://github.com/jskorlol/json-skeleton-mcp.git
cd json-skeleton-mcp
- 创建虚拟环境并安装：
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）。
- 在正常模式下，数字、布尔值和空值保持不变。
📚 详细文档
使用场景
- 理解API响应：快速掌握大型API响应的结构，无需处理数兆字节的数据。
- 文档编写：为API文档生成结构示例。
- 开发工作：处理数据结构，而无需处理大负载。
- 令牌优化：在使用AI模型时减少令牌使用。
- 模式发现：使用仅显示类型模式来理解复杂JSON结构中的数据类型。
测试
运行测试脚本来查看工具的实际效果：
# 测试基本功能
python test_skeleton.py
# 测试不同的max_length值
python test_max_length.py
# 测试仅显示类型模式
python test_type_only.py
要求
- Python 3.10+
- MCP库
📄 许可证
本项目采用MIT许可证。