Universal JSON Agent

БесплатноНе проверен

Enables natural language interaction with JSON files, providing tools to load, query, aggregate, transform, and export data directly from AI editors.

автор: GautamVhavle

GitHub Embed

Описание

Enables natural language interaction with JSON files, providing tools to load, query, aggregate, transform, and export data directly from AI editors.

README

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.

PyPI Python MCP Badge License CI Tests

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",
  "tools_used": ["load_json", "sum_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                            # 489 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 ⭐

from github.com/GautamVhavle/universal-json-agent

Установка Universal JSON Agent

У этого сервера нет опубликованного пакета — он собирается из исходников. Открой репозиторий и следуй инструкции в README.

▸ github.com/GautamVhavle/universal-json-agent

FAQ