# JSON Path Evaluator

**MCP Tool:** `json_path_evaluator`  
**Tier:** Tier 2 — Differentiated  
**Category:** analyzers  
**Endpoint:** https://obfus.link/mcp  
**Price:** $0.015 / call  
**Verification:** ✓ TDD verified  

> Extract values from JSON with dual JSONPath + jq syntax and path suggestions

## Atomic Answer

JSON Path Evaluator extracts values from any JSON document using JSONPath or jq syntax in a single tool. Path Suggestions analyses unknown structures and recommends ranked extraction expressions, letting agents discover paths without knowing the schema. Returns matches, canonical bracket-notation paths, and a tree overview giving depth, total keys, array items, and top-level keys.

## Description

Industrial JSON extraction with two production engines under one interface: jsonpath-plus for full JSONPath support (filters, slices, unions, recursive descent) and jq-web (WASM) for full jq support (pipes, select/map/reduce, arithmetic, all standard functions). Returns matches, canonical paths, and a Tree overview. Path Suggestions recommends extraction expressions in the chosen syntax.

## Agentic Reasoning

USE THIS WHEN: (1) You received a JSON payload from an unknown API and need to extract specific values without writing custom parsing code — pass the JSON and a JSONPath expression like "$.data.items[*].id" and get back the matches[] array plus canonical paths[]. (2) You don't know the schema and need to discover extraction paths — pass suggestPaths: true and the tool returns ranked candidate expressions in your chosen syntax, including recursive expressions for ID-like fields. (3) You are working in a jq-native CLI/Unix pipeline but the upstream tool returned JSONPath, or vice versa — feed the document in once and use whichever syntax fits; both engines produce identical match arrays for equivalent expressions. (4) You need both the value AND the path back — paths[] uses canonical bracket notation ($['key'][0]['nested']) so values can be located even when keys contain dots. (5) You need real filter/transformation power — JSONPath filter expressions ([?(@.price<10)]) AND jq select/map/reduce are both supported via the production engines (jsonpath-plus and jq-web WASM). DO NOT USE WHEN: you need to mutate the document — there is no setter or update path; both engines are read-only extractors. Do not use to validate JSON against a schema — use json_to_zod or env_validator instead. OVER ALTERNATIVES: prefer this over a one-off JSON.parse + manual property traversal (no path tracking, no recursive search, no agent-friendly error envelope), over installing jq as a system dependency in agent pipelines (heavyweight, OS-specific, no programmatic Tree overview), and over wiring up jsonpath-plus + jq-web separately (this tool unifies their error envelopes, output shapes, and provides cross-syntax equivalence checking out of the box).

## MCP Description

Industrial JSON extraction backed by two production engines: jsonpath-plus for JSONPath and jq-web (WASM, lazy-loaded) for jq. Returns matches, canonical paths, and a Tree overview (depth, totalKeys, totalArrayItems, topLevelKeys). Dual syntax (★ differentiator) in a single tool. Path Suggestions (★ differentiator): pass suggestPaths: true and the tool performs a shallow crawl and returns up to 10 ranked extraction expressions. JSONPath supports the full spec: $ root, .foo child, [N], [*], ['key'], ..foo recursive descent, [?(@.x>10)] filter expressions, [0:2] slices, [1,3,5] unions. jq supports the full language: pipes, select, map, reduce, arithmetic, all standard functions. Syntax errors surface verbatim from each engine via INPUT_MALFORMED. USE WHEN: extracting values from JSON payloads, discovering extraction paths in unknown schemas, or running real filters/transformations without installing jq. INPUT: json (string or object), expression, syntax ("jsonpath" | "jq"), optional suggestPaths boolean. COST: 1 unit.

## Input Schema

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `json` | `any` | yes | The JSON to query. Either a JSON string (will be parsed) or an already-parsed object/array. |
| `syntax` | `jsonpath` \| `jq` | yes | Which query language the expression is written in. |
| `expression` | `string` | yes | Extraction expression. Must match the chosen syntax. |
| `suggestPaths` | `boolean` | no | When true, analyses the JSON structure and returns up to 10 ranked extraction expressions. |

## Output Schema

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tree` | `object` | no |  |
| `paths` | `array` | yes | Canonical bracket-notation path to each match, e.g. $['store']['book'][0]['author'] |
| `matches` | `array` | yes | Values matched by the expression |
| `matchCount` | `number` | yes |  |
| `suggestions` | `array` | no | Present only when suggestPaths: true. Ranked extraction recommendations. |

## How To Use

1. **Paste your JSON** — Drop any JSON object or array into the document field. Both strings and pre-parsed objects work when calling via MCP.
2. **Pick syntax** — JSONPath for web/JavaScript pipelines, jq for CLI/Unix pipelines. Equivalent expressions produce identical results.
3. **Write the expression** — Use the syntax of your choice. The placeholder shows a canonical example for each.
4. **Toggle Suggest paths** — When ON, the tool returns up to 10 ranked extraction expressions analysing your JSON's structure — useful when the schema is unknown.
5. **Run and inspect** — Each match shows its canonical path so you can find values that share a key in multiple places. Click a suggestion to use it.

## FAQs

**What's the difference between JSONPath and jq?**

JSONPath uses $ as the root anchor and dot-or-bracket child syntax: $.foo.bar, $.foo[*], $..price. jq uses dot-leading paths and square brackets for iteration: .foo.bar, .foo[], .[]. JSONPath dominates web/JavaScript code; jq dominates CLI/Unix pipelines. Both produce identical match arrays for equivalent expressions in this tool.

**Which JSONPath features are supported?**

The full JSONPath spec via jsonpath-plus: $ (root), .foo (child), [N] (index), [*] (wildcard), ['key'] (bracket child), ..foo (recursive descent), [?(@.x>10)] (filter expressions), [0:2] (slices), and [1,3,5] (unions). Filter expressions can reference @ to compare fields against literals or other fields. Script expressions like [(@.length-1)] are not enabled for security.

**Which jq features are supported?**

The full jq language via jq-web (WASM): pipes, select, map, reduce, arithmetic, string manipulation, type conversion, and every standard built-in. The WASM binary is lazy-loaded on the first jq invocation per process — JSONPath-only callers never pay the load cost.

**How does Path Suggestions decide what to recommend?**

Three strategies, ranked by matchCount: (1) top-level keys when the root is an object, or array index + wildcard when the root is an array; (2) recursive expressions for ID-like fields anywhere in the document (id, uuid, guid, token, hash, key, sku, slug); (3) for any array of objects with a common shape, the top 3 keys present in every item.

**What does the Tree overview tell me?**

depth = the maximum nesting level. totalKeys = every object key counted at every depth. totalArrayItems = every array element counted at every depth. topLevelKeys = the keys at the root when the root is an object. Together they describe the document's shape before you write an extraction expression — useful for agents reasoning about an unknown payload.

**Can I use this tool via the MCP API?**

Yes. The tool is registered on the obfus.link MCP server at https://obfus.link/mcp. Call it from any MCP-compatible agent with a Shared Payment Token. The MCP tool name matches the snake_case slug shown in the integration snippet.

## Tags

`json` · `jsonpath` · `jq` · `extraction` · `query` · `analyzer` · `tree` · `schema-discovery`

---

*obfus.link — A Subether Labs Infrastructure Project*  
*Canonical URL: https://obfus.link/tool/json-path-evaluator*  
*JSON view: https://obfus.link/tool/json-path-evaluator/json*