Universal JSON Agent

通用JSON代理MCP

使用自然语言与JSON文件对话。

26个强大的工具 直接从您的AI编辑器加载、探索、查询、聚合、转换和导出。

uv tool install universal-json-agent-mcp

入门指南 · 26工具 · 网络服务器 · 发展

______________________________________________________________________

为什么？

使用JSON不应该每次都需要编写脚本。这个工具可以让你用简单的英语提问，并立即得到答案。

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)

支持的客户

______________________________________________________________________

⚡ 入门指南

1.安装

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.配置编辑器

VS Code / GitHub Copilot

创建 .vscode/mcp.json 在您的工作空间中：

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

提示： 更喜欢零安装？使用 "command": "uvx" 和 "args": ["universal-json-agent-mcp"] 相反。

Claude Desktop

添加 claude_desktop_config.json:

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

Cursor

添加到光标MCP设置中：

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

CLI / Standalone

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

开始 标准 --将任何MCP客户端导入其中。

3.开始提问

> 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

______________________________________________________________________

🛠 工具参考

加载和管理

探索

查询

聚合

变换

分析

出口

内省

______________________________________________________________________

🌐 Web服务器子项目（Web/）

可选的 FastAPI+语言链 此仓库中的web服务器子项目，封装了用于集成、仪表板或非MCP工作流的所有26个根MCP工具。

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

端点

示例

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"]
}

配置

______________________________________________________________________

🧑‍💻 发展

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

释放

发布是通过GitHub Actions完全自动化的：

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

然后 对于标签，CI运行测试、构建并发布到PyPI。

______________________________________________________________________

故障排除

MCP server not appearing in Copilot / Claude / Cursor

1. 验证配置文件是否存在(.vscode/mcp.json VS代码）
2. 检查命令是否在PATH上： which universal-json-agent-mcp
3. 重新启动编辑器

"No document loaded" errors

您需要先加载一个文件。问你的AI： *“加载文件data/example.json”* --这叫 load_json 在幕后。

Truncated output

较大的结果限制在约10 KB。使用更具体的路径、过滤器或 pick_fields 缩小结果。

429 Too Many Requests (web server)

模型提供商正在限制您的速率。请稍等，或切换到您的 .env 文件。

Import errors in web server

uv sync --extra web

______________________________________________________________________