使用说明

Universal JSON Agent MCP

Talk to your JSON files using natural language.

26 powerful tools to load, explore, query, aggregate, transform, and export — right from your AI editor.

uv tool install universal-json-agent-mcp

Getting Started · 26 Tools · Web Server · Development

Why?

Working with JSON shouldn't require writing a script every time. This tool lets you ask questions in plain English and get answers instantly.

You:  What's the total budget across all missions?

AI:   The total budget across all missions is $18,250,000,000.50
      (Used tools: load_json → sum_values)

Supported Clients

			Any MCP Client
VS Code / Copilot	Claude Desktop	Cursor	stdio

⚡ Getting Started

1. Install

uv tool install universal-json-agent-mcp   # install CLI once
uvx universal-json-agent-mcp               # run without installing
uv add universal-json-agent-mcp            # add dependency to your project

2. Configure your editor

VS Code / GitHub Copilot

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "universal-json-agent": {
      "type": "stdio",
      "command": "universal-json-agent-mcp"
    }
  }
}

Tip: Prefer zero-install? Use "command": "uvx" with "args": ["universal-json-agent-mcp"] instead.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "universal-json-agent": {
      "command": "universal-json-agent-mcp"
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "universal-json-agent": {
      "command": "universal-json-agent-mcp"
    }
  }
}

CLI / Standalone

universal-json-agent-mcp
# or
uv run python -m universal_json_agent_mcp

Starts on stdio — pipe any MCP client into it.

3. Start asking questions

> Load data/orders.json and tell me what's inside
> How many missions have status "in_progress"?
> What's the total budget across all missions?
> Filter personnel where role contains "engineer"
> Sort by priority descending and show codenames
> Export the filtered results to CSV

🛠 Tools Reference

Load & Manage

Tool	What it does
`load_json`	Load a JSON file from disk into memory
`list_loaded`	List all loaded documents with metadata
`unload_json`	Remove a document from memory

Explore

Tool	What it does
`get_keys`	Get keys of an object or index range of an array
`get_value`	Retrieve value at a path (auto-truncated at 10 KB)
`get_type`	Return the JSON type at a path
`get_structure`	Schema-like skeleton — keys, types, nesting

Query

Tool	What it does
`jsonpath_query`	Run JSONPath — `$.missions[*].codename`
`filter_objects`	Filter by condition: `eq`, `gt`, `lt`, `contains`, `regex`…
`search_text`	Full-text search across all string values

Aggregate

Tool	What it does
`count`	Count items in an array or keys in an object
`sum_values`	Sum numeric values at a JSONPath
`min_max`	Get min and max of numeric values
`unique_values`	Distinct values at a JSONPath
`value_counts`	Frequency table — like pandas `value_counts()`

Transform

Tool	What it does
`flatten`	Flatten nested objects to dot-notation pairs
`pick_fields`	Project specific fields from array objects
`group_by`	Group objects by a field value
`sort_by`	Sort objects by a field
`sample`	Random N items from an array

Analytics

Tool	What it does
`describe`	Stats: count, mean, std, min, max, percentiles
`multi_filter`	Compound filters with AND / OR logic
`compare`	Diff two values — added, removed, changed keys

Export

Tool	What it does
`export_csv`	Export array of objects to CSV file
`export_json`	Export a value to a new JSON file

Introspect

Tool	What it does
`distinct_paths`	List every unique leaf path with types

🌐 Web Server Subproject (web/)

Optional FastAPI + LangChain web-server subproject inside this repo, wrapping all 26 root MCP tools for integrations, dashboards, or non-MCP workflows.

uv sync --extra web                       # install web deps with uv
cp .env.example .env                     # add your OpenRouter key
uv run python -m web.run --port 8000     # start server with uv
# open docs in browser: http://127.0.0.1:8000/docs

Endpoints

Method	Endpoint	Description
`GET`	`/health`	Health check
`POST`	`/query`	Upload JSON + ask a question
`POST`	`/query/path`	Reference a file on disk + ask a question
`GET`	`/docs`	Interactive Swagger UI

Example

curl -X POST http://localhost:8000/query \
  -F "file=@data/missions.json" \
  -F "query=What's the total budget?"

{
  "answer": "The total budget across all missions is $18,250,000,000.50",
  "steps": [
    {"tool": "load_json", "output": "Loaded 'missions' from data/missions.json"},
    {"tool": "sum_values", "output": "Sum: 18250000000.5  (from 4 values)"}
  ]
}

Configuration

Variable	Required	Default	Description
`OPENROUTER_API_KEY`	✅	—	Your OpenRouter API key
`OPENROUTER_MODEL`	—	`openai/gpt-4o-mini`	Any supported model

🧑‍💻 Development

git clone https://github.com/GautamVhavle/universal-json-agent.git
cd universal-json-agent
uv sync --extra dev
uv run pytest                            # 503 tests

More test commands

uv run pytest -v                                        # verbose
uv run pytest tests/test_tools/test_aggregate.py        # one file
uv run pytest -k "test_filter"                          # by pattern

Releasing

Releases are fully automated via GitHub Actions:

git tag v0.3.0 -m "v0.3.0"
git push origin v0.3.0

Then create a GitHub Release for the tag — CI runs tests, builds, and publishes to PyPI.

Troubleshooting

MCP server not appearing in Copilot / Claude / Cursor

Verify the config file exists (.vscode/mcp.json for VS Code)
Check the command is on your PATH: which universal-json-agent-mcp
Restart the editor

"No document loaded" errors

You need to load a file first. Ask your AI: "Load the file data/example.json" — this calls load_json behind the scenes.

Truncated output

Large results are capped at ~10 KB. Use more specific paths, filters, or pick_fields to narrow results.

429 Too Many Requests (web server)

The model provider is rate-limiting you. Wait a moment or switch to a different model in your .env file.

Import errors in web server

uv sync --extra web

MIT License · Built with ❤️ by Gautam Vhavle · Star this repo if it helped you ⭐