Json Skeleton MCP

🚀 JSON Skeleton MCP Server

JSON Skeleton MCP Serverは、大きなJSONファイルのコンパクトな「スケルトン」表現を作成する軽量なMCP（Model Context Protocol）サーバーです。これにより、大量のデータを読み込まずにJSON構造を理解することができます。

🚀 クイックスタート

JSON Skeleton MCP Serverを使えば、大きな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 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（Data Transfer Object）構造を比較することでスマートに重複排除します。

• プリミティブ配列の場合: 最大3つの一意の値を保持します。
• オブジェクト配列の場合: 各一意の構造の1つの例を保持します。
• 構造の比較は、実際の値ではなくキーと値の型に基づいて行われます。
• 型のみモードでは: 配列の最初の要素の型のみを表示します。

値の処理

• 通常モード：最大長を超える文字列は「...(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ライセンス