# MCP JSON Lens

[![CI](https://github.com/KaryawanSurga/mcp-json-lens/actions/workflows/ci.yml/badge.svg)](https://github.com/KaryawanSurga/mcp-json-lens/actions/workflows/ci.yml)
[![Node](https://img.shields.io/badge/node-%3E%3D20-339933)](package.json)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**Look at big JSON without loading big JSON.**

MCP JSON Lens is an MCP server and CLI that summarize and query JSON and JSONL files with a small jq-like expression language. Ask for the shape of a document, or pull exactly the values you need — the rest never reaches your context. Use it as an MCP tool so agents can explore datasets safely, or straight from the terminal.

Sixth tool in the TokenSaver family: [TokenSaver MCP](https://github.com/KaryawanSurga/TokenSaverMcp) maps repositories, [MCP Context Budget](https://github.com/KaryawanSurga/mcp-context-budget) audits tool costs, [MCP Web Snapshot](https://github.com/KaryawanSurga/mcp-web-snapshot) reads the web, [MCP Log Tail](https://github.com/KaryawanSurga/mcp-log-tail) summarizes logs, [MCP Secret Scan](https://github.com/KaryawanSurga/mcp-secret-scan) guards commits, and JSON Lens explores data.

> Product requirements: [PRD.md](PRD.md) · [PRD.id.md](PRD.id.md) (Bahasa Indonesia)

## Why

The fastest way to destroy a context window is pasting a large JSON file into it. But agents constantly need to answer small questions about big data: what shape is this export, which records failed, what are the ids. JSON Lens answers those questions with compact, bounded output instead of the whole document.

## Quick start

Inspect structure — no expression needed:

```sh
npx -y mcp-json-lens inspect ./data.json
```

```text
# JSON inspection: ./data.json
Kind: json | 198 B
Type: object (3 keys)
- users: array[3] of object
    items:
    - id: number (sample 1)
    - name: string (sample "Ada")
    - roles: array[2]
- total: number (sample 3)
- page: number (sample 1)
```

Query values with a jq-like expression:

```sh
npx -y mcp-json-lens query ./data.json --expr '.users[*].name'
```

```text
# Query: .users[*].name
Kind: json | matches: 3 | showing: 3

[
  "Ada",
  "Budi",
  "Citra"
]
```

Works the same on JSONL, with line numbers:

```sh
npx -y mcp-json-lens query ./events.jsonl --expr '.level, .user' --limit 2
```

```json
[
  { "line": 1, "value": { ".level": "info", ".user": "ada" } },
  { "line": 2, "value": { ".level": "error", ".user": "budi" } }
]
```

## Expression cheatsheet

| Expression | Meaning |
| --- | --- |
| `.users[*].name` | Every name in the users array |
| `.items[0]`, `.items[-1]` | First and last item |
| `.[*]` | Iterate the root array or object |
| `.id, .name` | Multiple paths — returns an object per record |
| `.items \| length` | Pipe: `length` |
| `.meta \| keys` | Pipe: `keys` |
| `.total \| type` | Pipe: `type` |

Pipes: `keys`, `length`, `type`. Multiple paths and pipes cannot be combined in v0.1.0.

## MCP server

Add it to any MCP-compatible client:

```json
{
  "mcpServers": {
    "jsonlens": {
      "command": "npx",
      "args": ["-y", "mcp-json-lens", "serve"]
    }
  }
}
```

From a local checkout, point `command` at `node` and `args` at the built entry point:

```json
{
  "mcpServers": {
    "jsonlens": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-json-lens/dist/index.js", "serve"]
    }
  }
}
```

## Tools

| Tool | What it returns |
| --- | --- |
| `inspect_json` | Types, keys, array lengths, and samples — up to a depth limit and output budget. |
| `query_json` | Matching values for an expression, limited by count and token budget, with truncation reported. |

## Design principles

- **Bounded**: file size caps, line caps, result limits, and token budgets everywhere.
- **Offline**: no network, no telemetry; data never leaves your machine.
- **Read-only**: never writes to your files.
- **Format-tolerant**: JSON and JSONL, including mislabeled files.
- **Honest**: truncation and omitted keys are always reported.

## CLI reference

```text
mcp-json-lens inspect <file> [--json]
mcp-json-lens query <file> --expr <expression> [--limit <n>] [--json]
mcp-json-lens serve
```

Exit codes: `0` success, `1` file or expression failure, `2` usage error.

## Roadmap

- More pipes: `sort`, `unique`, `map(.field)`, `select(.field == value)`.
- Bracket-quoted keys (`.["weird key"]`) and slices (`.[1:5]`).
- Streaming JSONL queries with early exit for very large files.
- NDJSON output mode for piping between tools.
- CSV and Parquet inspection.

## Development

```sh
npm install
npm run typecheck
npm run build
npm test
```

The suite covers the expression parser and evaluator, schema summarization, JSON and JSONL loading, query execution, rendering, CLI behavior, and MCP round trips.

## License

MIT — see [LICENSE](LICENSE).