MCP JSON Tools

MCP JSON Tools

简体中文

強力なデータ操作機能を備えた Lodash と JSONPath によるクエリを使用して、ローカルの JSON ファイルおよび NDJSON ファイルを操作します。 mcp_json_eval および mcp_json_multi_eval ツールで、操作には lodash を、クエリには jsonpath を利用します。

主な機能

• 形式の統一処理：標準的な JSON と改行区切り JSON（NDJSON/JSONL）の両方を自動的に読み込みます。NDJSON ファイルはオブジェクトの配列として扱われます。
• クエリ：標準的な JSONPath 式を使って、JSON または NDJSON ファイルからデータを選択します（mcp_json_query）。
• 検査：JSON/NDJSON 構造内の値とその正確なパスを取得します（mcp_json_nodes）。
• 分析と変更：サンドボックス化された VM 内で JavaScript（Lodash の _ と JSONPath の jp を使用）を実行し、JSON/NDJSON ファイルの複雑な分析や変更を行います（mcp_json_eval、mcp_json_multi_eval）。変更後も元のファイル形式（JSON または NDJSON）が保持されます。
• 安全な実行：eval ツールで、より安全なコード実行のために Node.js の vm モジュールを使用し、タイムアウトを設定できます。
• 簡単なセットアップ：標準的な Node.js プロセスとして npx 経由で実行します。

提供するツール

1. mcp_json_query

• アクション：ローカルの JSON または NDJSON ファイルに対して JSONPath クエリを実行し、一致する値を返します。両方の形式を自動的に読み込みます。NDJSON はクエリ時にオブジェクトの配列として扱われます。
• パラメーター：
  • file_path (string)：JSON または NDJSON ファイルへのパス。
  • json_path (string)：JSONPath クエリ。構文に関する注意：
    • 標準的な JSON（ルートがオブジェクト）の場合、パスは通常 $. で始まります（例：$.store.book[*].author）。
    • NDJSON（ルートが配列）の場合、パスは $ の後に [ を続ける必要があります（例：$[?(@.user=='alice')].event または $[*].user）。ルート配列に対して $[*][?(...)] を使用しても、期待どおりに動作しません。
  • count (number、任意)：結果の最大数。
• 戻り値：一致した値の配列。
• 例：すべての書籍の著者を取得する（JSON から）
  • 目的：store.json からすべての著者名を取得します。
  • ツールの呼び出し：file_path="test-data/store.json" および json_path="$.store.book[*].author" を指定して mcp_json_query を呼び出します。
  • 想定される出力：["Nigel Rees", "Evelyn Waugh", "Herman Melville", "J. R. R. Tolkien"]
• 例：ユーザー 'alice' のイベント種別を取得する（NDJSON から）
  • 目的：events.ndjson からユーザー 'alice' のイベント種別を取得します。
  • ツールの呼び出し：file_path="{abspath}/mcp-json-tools/test-data/events.ndjson" および json_path="$[?(@.user=='alice')].event" を指定して mcp_json_query を呼び出します。（ルート配列には $[?(...)] 構文を使用してください。）
  • 想定される出力：["login", "login", "view_item"]（文字列化された配列として）

2. mcp_json_nodes

• アクション: ローカルの JSON または NDJSON ファイルに対して JSONPath クエリを実行し、一致するノード（値とパス）を返します。両方の形式を自動的に読み込みます。NDJSON はクエリ時にオブジェクトの配列として扱われます。
• パラメーター:
  • file_path (string): JSON または NDJSON ファイルへのパス。
  • json_path (string): JSONPath クエリ。構文に関する注意:
    • 標準的な JSON（ルートがオブジェクト）の場合、パスは通常 $. で始まります（例：$.store.book[?(@.price<10)]）。
    • NDJSON（ルートが配列）の場合、パスは $ の後に [ を続ける必要があります（例：$[?(@.user=='bob')] または $[*]）。ルート配列に対して $[*][?(...)] を使用しても、期待どおりに動作しません。
  • count (number, optional): 結果の最大数。
• 戻り値: { path: Array<string|number>, value: any } 形式のオブジェクトの配列。
• 例：パス付きで作成者を取得（JSON から）
  • 目的: store.json から作成者とその位置を取得します。
  • ツールの呼び出し: file_path="test-data/store.json" および json_path="$.store.book[*].author" を指定して mcp_json_nodes を呼び出します。
  • 予想される出力（簡略版）: [ { path: ['$', 'store', 'book', 0, 'author'], value: 'Nigel Rees' }, ... ]
• 例：ユーザー 'bob' のイベントオブジェクト全体を取得（NDJSON から）
  • 目的: events.ndjson から、ユーザー "bob" のイベントオブジェクト全体（パスを含む）を取得します。
  • ツールの呼び出し: file_path="{abspath}/mcp-json-tools/test-data/events.ndjson" および json_path="$[?(@.user=='bob')]" を指定して mcp_json_nodes を呼び出します。（ルート配列には $[?(...)] 構文を使用することに注意してください）。
  • 予想される出力: bob のイベントのノードオブジェクト {path: ..., value: ...} を含む、文字列化された JSON 配列。

3. mcp_json_eval

• アクション：JSON または NDJSON ファイルを読み込み、ファイルの内容（$1：JSON の場合はオブジェクト、NDJSON の場合はオブジェクトの配列）、lodash（_）、jsonpath（jp）を使用できるサンドボックス化された VM 内で JavaScript コードを実行します。結果を返すか、コードの最後の式が { type: 'updateFile', data: <new_data> } の場合はファイルを変更します（元の形式である JSON または NDJSON を維持します）。タイムアウトは 30 秒です。
• パラメーター：
  • file_path（string）：JSON または NDJSON ファイルのパスです。
  • js_code（string）：実行する JavaScript コードです。
• ファイルの変更：ファイルへの書き込みを実行するには、js_code で評価される最後の式が ({ type: 'updateFile', data: <new_data> }) である必要があります。形式を維持する場合、<new_data> は期待される構造（JSON の場合はオブジェクト、NDJSON の場合は配列）と一致している必要があります。
• 戻り値：
  • 最後の式が更新命令ではない場合：js_code の実行結果をそのまま返します（オブジェクトまたは配列は文字列化し、それ以外はプリミティブ値を返します）。
  • 最後の式が更新命令の場合：ファイルの書き込みに成功すると、成功メッセージを返します（例："Successfully updated json file: ..." または "Successfully updated ndjson file: ..."）。
• ⚠️ セキュリティに関する警告 ⚠️：ユーザー提供のコードをサンドボックス化された VM 内で実行します。生の eval() より安全ですが、リソースの枯渇や意図しないロジックが発生する可能性があるため、コードを確認してください。信頼できるコードで使用してください。
• 例：onSale プロパティを追加する（JSON の変更）
  • 目的：store.json のすべての書籍に onSale: false を追加します。
  • JavaScript のロジック：

    // $1 is the JSON object
    _.forEach($1.store.book, (book) => {
      book.onSale = false;
    });
    ({ type: 'updateFile', data: $1 }); // Return update object
    

  • ツールの呼び出し：file_path="test-data/store.json" を指定し、上記の JavaScript ロジックを js_code パラメーターに指定して、mcp_json_eval を呼び出します。
  • 想定される出力："Successfully updated json file: test-data/store.json"
• 例：平均価格を計算する（JSON の分析）
  • 目的：store.json にある安価なフィクション書籍の平均価格を求めます。
  • JavaScript のロジック：

    // $1 is the JSON object
    const books = jp.query($1, "$.store.book[?(@.category=='fiction' && @.price < 15)]");
    _.meanBy(books, 'price'); // Return the average price
    

  • ツールの呼び出し：file_path="test-data/store.json" を指定し、上記の JavaScript ロジックを js_code パラメーターに指定して、mcp_json_eval を呼び出します。
  • 想定される出力：10.99
• 例：失敗したイベントを除外する（NDJSON の変更）
  • 目的：test-data/events.ndjson から success が false のイベントを削除し、ファイルを更新します。
  • JavaScript のロジック：

    // $1 is the array of event objects from the NDJSON file
    const filteredData = _.filter($1, item => item.success === true);
    // Return the update object with the filtered array
    ({ type: 'updateFile', data: filteredData }); 
    

  • ツールの呼び出し：file_path="{abspath}/mcp-json-tools/test-data/events.ndjson" と JS ロジックを指定して、mcp_json_eval を呼び出します。
  • 想定される出力："Successfully updated ndjson file: {abspath}/mcp-json-tools/test-data/events.ndjson"

4. mcp_json_multi_eval

• アクション：複数の JSON または NDJSON ファイルを読み込み、ファイルの内容（$1 は各要素がファイルの解析済みコンテンツである配列です。JSON の場合はオブジェクト、NDJSON の場合は配列）、lodash（_）、jsonpath（jp）を使って、サンドボックス化された VM 内で JS コードを実行します。結果を返すか、コードの最後の式が { type: 'updateMultipleFiles', updates: [{ index: <file_index>, data: <newData> }, ...] } の場合は、元の形式を保持したままファイルを変更します。タイムアウトは 30 秒です。
• パラメーター：
  • file_paths（文字列の配列）：JSON または NDJSON ファイルのパスです。
  • js_code（文字列）：実行する JavaScript コードです。
• ファイルの変更：ファイルへの書き込みを実行するには、js_code で評価される最後の式が、必ず ({ type: 'updateMultipleFiles', updates: [{ index: <file_index>, data: <newData> }, ...] }) である必要があります。入力された file_paths の有効なインデックスに対応するファイルのみ更新できます。<newData> は、そのインデックスのファイルの元の形式と一致している必要があります。
• 戻り値：
  • 最後の式が複数ファイルの更新指示ではない場合：js_code の実行結果をそのまま返します（オブジェクトまたは配列の場合は文字列化され、それ以外の場合はプリミティブ値が返されます）。
  • 最後の式が複数ファイルの更新指示の場合：更新されたファイルを列挙した成功メッセージが返されます（例："Successfully updated files: ..."）。
• ⚠️ セキュリティ警告 ⚠️：ユーザーが指定したコードを、サンドボックス化された VM 内で実行します。セキュリティに関する考慮事項は mcp_json_eval と同じです。

設定

クライアント（Cursor、VS Code）で、npx を使用してサーバーを実行するよう設定します。これにより、サーバーコマンド自体に絶対パスを指定する必要がなくなります。

NPX を使用する（推奨）：

• ファイルパスに関する重要な注意：NPX を使用する場合、ツールに渡す file_path または file_paths は絶対パスである必要があります。npx がコマンドを実行する仕組みにより、相対パスは正しく解決されない場合があります。

• Cursor（.cursor/mcp.json）：

  {
    "mcpServers": {
      "jsonTools": {
        "description": "ローカルの JSON および NDJSON ファイルを照会、検査、変更するツールです。",
        "command": "npx",
        "args": [ "mcp-json-tools" ] 
      }
    }
  }
  

• VS Code（.vscode/mcp.json またはユーザー設定）：

  {
    "jsonTools": {
      "description": "ローカルの JSON および NDJSON ファイルを照会、検査、変更するツールです。",
      "command": "npx",
      "args": [ "mcp-json-tools" ] 
    }
  }
  

別の方法：Node を直接使用する

この方法では、mcp.json の設定にある args 配列で、mcp-json-tools/index.js ファイルの絶対パスを指定する必要があります（例："command": "node", "args": [ "/abs/path/to/mcp-json-tools/index.js" ]）。NPX を使用する方法よりも移植性が低くなります。

この方法を使用するには、まずコードをローカルに用意する必要があります。

1. Node.js が必要です（バージョン 18 以上を推奨）。
2. リポジトリをクローンします：git clone https://github.com/zfirsty/mcp-json-tools.git
3. ディレクトリに移動します：cd mcp-json-tools
4. 依存関係をインストールします：npm install（@modelcontextprotocol/sdk、jsonpath、lodash、zod をインストールします）。 次に、クローンした index.js ファイルの絶対パスを使用するよう、クライアントを設定します。

ライセンス

MIT ライセンスです。詳細は LICENSE ファイルをご覧ください。