JSON Skeleton MCP Server

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

特性

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

安装

使用uvx快速启动（推荐）

您可以直接运行MCP服务器而不进行安装，使用uvx：

# 从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 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：基本用法

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

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

输入：json_skeleton(file_path="/path/to/data.json", max_length=50)
输出：更激进地截断至50个字符的JSON

示例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）
• 数字、布尔值和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许可证