MCP Query JSON File

An MCP (Model Context Protocol) server that provides JSON file querying capabilities using the jq command-line processor. This server allows you to execute jq queries on JSON files, generate schemas, and maintain an audit trail of all queries.

Features

• JSON Querying: Execute jq queries on JSON files with structured responses
• Schema Generation: Generate JSON schemas from existing JSON files
• Audit Logging: Complete audit trail of all query executions
• Size Validation: Configurable limits to prevent oversized responses
• Cross-Platform: Works on Windows, Linux, and macOS

Installation

npm install -g @berrydev-ai/mcp-query-json-file

Configuration

The server requires the following environment variables:

| Variable | Required | Default | Description | | ---------------- | -------- | ------------- | ------------------------------ | | JSON_FILE_PATH | Yes | - | Path to the JSON file to query | | JQ_PATH | Yes | - | Path to the jq executable | | MAX_DATA_SIZE | No | 1000000 | Maximum result size in bytes | | LOG_FILE_PATH | No | ./query.log | Path to the audit log file |

Claude Desktop Setup

Add the following configuration to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-query-json-file": {
      "command": "npx",
      "args": ["-y", "@berrydev-ai/mcp-query-json-file"],
      "env": {
        "JSON_FILE_PATH": "/path/to/your/data.json",
        "JQ_PATH": "/opt/homebrew/bin/jq",
        "MAX_DATA_SIZE": "1000000",
        "LOG_FILE_PATH": "/var/logs/mcp-query-json-file.log"
      }
    }
  }
}

Usage Examples

Basic Queries

Get all users:

queryJson with query: ".users"

Filter active users:

queryJson with query: ".users[] | select(.active == true)"

Get user names only:

queryJson with query: ".users[].name"

Count total users:

queryJson with query: ".users | length"

Advanced Queries

Group users by status:

queryJson with query: "group_by(.active) | map({active: .[0].active, count: length})"

Sort users by age:

queryJson with query: ".users | sort_by(.age)"

Schema Generation

Generate a JSON schema from your data:

generateSchema

Query Statistics

View query execution history:

getQueryStats with limit: 20

Tools

queryJson

Execute a jq query on the configured JSON file.

Parameters:

• query (string): The jq query to execute

Response:

{
  "query": ".users[0]",
  "resultSize": 156,
  "result": {
    "id": 1,
    "name": "John Doe",
    "age": 30
  }
}

If the result exceeds the size limit:

{
  "query": ".users",
  "resultSize": 2500000,
  "warning": "Query result too large: 2500000 bytes exceeds limit of 1000000 bytes. Please refine your query to return less data.",
  "result": null
}

generateSchema

Generate a JSON schema from the configured JSON file.

Response:

{
  "filePath": "/path/to/data.json",
  "schema": {
    "type": "object",
    "properties": {
      "users": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": { "type": "number" },
            "name": { "type": "string" }
          }
        }
      }
    }
  }
}

getQueryStats

Get statistics about query execution history.

Parameters:

• limit (number, optional): Maximum number of recent queries to return (default: 10)

Response:

{
  "totalQueries": 25,
  "successfulQueries": 23,
  "failedQueries": 2,
  "recentQueries": [
    {
      "timestamp": "2024-01-01T12:00:00Z",
      "query": ".users[0]",
      "filePath": "/path/to/data.json",
      "resultSize": 156,
      "success": true
    }
  ]
}

Resources

queryLog

Read-only access to the complete audit trail of all query executions.

URI: queryLog Content-Type: application/json

Development

Prerequisites

• Node.js 18+
• jq command-line tool
• pnpm (recommended)

Setup

# Clone the repository
git clone <repository-url>
cd mcp-query-json-file

# Install dependencies
pnpm install

# Run tests
pnpm test

# Start development server
pnpm dev

Testing

The project includes comprehensive tests for:

• Configuration validation
• Query engine functionality
• Audit logging
• Error handling
• Cross-platform compatibility

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test --watch

Troubleshooting

jq Command Not Found

If you get "jq command not found" errors:

1. Install jq:

   • macOS: brew install jq
   • Ubuntu/Debian: sudo apt-get install jq
   • Windows: Download from https://stedolan.github.io/jq/

2. Or specify custom path:

   "env": {
     "JQ_PATH": "/usr/local/bin/jq",
     "JSON_FILE_PATH": "/path/to/data.json"
   }

Large Result Sets

If queries return "too large" warnings:

1. Increase the limit:

   "env": {
     "MAX_DATA_SIZE": "5000000"
   }

2. Or refine your queries:

   • Use limit(n) to restrict results: .users | limit(10)
   • Select specific fields: .users[] | {name, age}
   • Add filters: .users[] | select(.active == true)

File Permissions

Ensure the process has read access to your JSON file and write access to the log directory.

Local Test

node ./dist/index.js \
  --json-file-path=./tests/fixtures/sample.json \
  --jq-path=/opt/homebrew/bin/jq \
  --max-data-size=1000000 \
  --log-file-path=./mcp-query-json-file.log

License

MIT