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許可證。