{"_id":"@berrydev-ai/mcp-query-json-file","_rev":"4-78ef1c686e0f4a13216026e3983038dc","name":"@berrydev-ai/mcp-query-json-file","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@berrydev-ai/mcp-query-json-file","version":"1.0.0","keywords":["mcp","json","jq","query"],"author":{"url":"eric@berrydev.ai","name":"Eric Berry"},"license":"MIT","_id":"@berrydev-ai/mcp-query-json-file@1.0.0","maintainers":[{"name":"coderberry","email":"coderberry@gmail.com"}],"bin":{"mcp-query-json-file":"dist/index.js"},"dist":{"shasum":"b006aa86ac8ac583bef97544dbe55664db3cbfc2","tarball":"https://registry.npmjs.org/@berrydev-ai/mcp-query-json-file/-/mcp-query-json-file-1.0.0.tgz","fileCount":18,"integrity":"sha512-te3f5wclqO2Cgka/g1HbwW9n59BP99O5RdNZIrMbl6boe9lpb4lf1CGcxwWhn/fNk2waCLgKNT07XR+w82JqOg==","signatures":[{"sig":"MEUCIQDy7ZSaxAB8TBWT3mKj06kXvPSx+qzYaFxSmyKNaKODUQIgfTzLayZw++8ZOMbOoY7NVh8QMSBI+9f5iAPDnbDXHtw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30060},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"d26e675000bc7348fbabc9f0944ef512ae0a1a50","scripts":{"dev":"tsx src/index.ts","lint":"eslint . --ext .ts,.js --cache","test":"JQ_PATH=/opt/homebrew/bin/jq JSON_FILE_PATH=tests/fixtures/sample.json vitest run","build":"tsc && shx chmod +x dist/*.js","format":"prettier --write .","lint:fix":"eslint . --ext .ts,.js --fix --cache","typecheck":"tsc --noEmit","test:watch":"JQ_PATH=/opt/homebrew/bin/jq JSON_FILE_PATH=tests/fixtures/sample.json vitest","format:check":"prettier --check .","prepublishOnly":"npm run build"},"_npmUser":{"name":"coderberry","email":"coderberry@gmail.com"},"_npmVersion":"10.9.2","description":"MCP server for querying JSON files using jq processor","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.25.0","fastmcp":"^3.12.0","node-jq":"^6.0.1","genson-js":"^0.0.8"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.3.4","tsx":"^4.19.2","vitest":"^3.2.4","typescript":"^5.7.2","@types/node":"^22.10.2"},"_npmOperationalInternal":{"tmp":"tmp/mcp-query-json-file_1.0.0_1753804647621_0.9174305263465521","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@berrydev-ai/mcp-query-json-file","version":"1.0.1","keywords":["mcp","json","jq","query"],"author":{"url":"eric@berrydev.ai","name":"Eric Berry"},"license":"MIT","_id":"@berrydev-ai/mcp-query-json-file@1.0.1","maintainers":[{"name":"coderberry","email":"coderberry@gmail.com"}],"bin":{"mcp-query-json-file":"dist/index.js"},"dist":{"shasum":"562d05b01642ff2606f1fcd9892a21a376b7ead3","tarball":"https://registry.npmjs.org/@berrydev-ai/mcp-query-json-file/-/mcp-query-json-file-1.0.1.tgz","fileCount":18,"integrity":"sha512-+ECbmT1PfZTziptNGdd4wJ3lU34xndZQ60g9zOPVIaFeEVSPICIX/jyl09+nPNxlh/xFvfa95RPviHlReA7kug==","signatures":[{"sig":"MEQCIFSIF6W+LCDdYaeUn58aQYa6FyJPbhrG9WNyURIw19bzAiBb9Ohoh/Au9o82kio+6Q8yhwsIDemR7KQsHxcnyLKR+A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34095},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"50a7c1b0d1bc6eccb751f14b8f01154958d69b93","scripts":{"dev":"dotenv -- tsx src/index.ts","lint":"eslint . --ext .ts,.js --cache","test":"dotenv -- vitest run","build":"tsc && shx chmod +x dist/*.js","clean":"rm -rf dist","format":"prettier --write .","lint:fix":"eslint . --ext .ts,.js --fix --cache","typecheck":"tsc --noEmit","test:watch":"dotenv -- vitest","format:check":"prettier --check .","prepublishOnly":"npm run build"},"_npmUser":{"name":"coderberry","email":"coderberry@gmail.com"},"_npmVersion":"10.9.2","description":"MCP server for querying JSON files using jq processor","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.25.0","fastmcp":"^3.12.0","node-jq":"^6.0.1","genson-js":"^0.0.8"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.3.4","tsx":"^4.19.2","vitest":"^3.2.4","dotenv-cli":"^9.0.0","typescript":"^5.7.2","@types/node":"^22.10.2"},"_npmOperationalInternal":{"tmp":"tmp/mcp-query-json-file_1.0.1_1753813811259_0.39479011561648925","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@berrydev-ai/mcp-query-json-file","version":"1.0.2","keywords":["mcp","json","jq","query"],"author":{"url":"eric@berrydev.ai","name":"Eric Berry"},"license":"MIT","_id":"@berrydev-ai/mcp-query-json-file@1.0.2","maintainers":[{"name":"coderberry","email":"coderberry@gmail.com"}],"bin":{"mcp-query-json-file":"dist/index.js"},"dist":{"shasum":"6dbd645f33920d475a047da27376e0c806a35dff","tarball":"https://registry.npmjs.org/@berrydev-ai/mcp-query-json-file/-/mcp-query-json-file-1.0.2.tgz","fileCount":18,"integrity":"sha512-mv5i0bE8NRBCeNnl0mpKNMPLHIBzg4QAJjHSvH/5S70QBDJ9oXBXY0/jwaSKho9H9RElCnYVvuNgfzcmjMv5gA==","signatures":[{"sig":"MEQCIH+gn0+INkeZItcf5RAYmqvOfKLEGwCL2GwOwL3ewaCGAiBWLq/zcvVVVgtCMaxoXshNl3h/D4/Sdv+ABQ36f5Zd6A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":36114},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"86e2d5725edeb5e0b4340a9a3cbc42e4bdbfd711","scripts":{"cli":"npx @wong2/mcp-cli -c ./claude_desktop_config.json","dev":"dotenv -- tsx src/index.ts","lint":"eslint . --ext .ts,.js --cache","test":"dotenv -- vitest run","build":"tsc && shx chmod +x dist/*.js","clean":"rm -rf dist","format":"prettier --write .","lint:fix":"eslint . --ext .ts,.js --fix --cache","typecheck":"tsc --noEmit","preinstall":"cross-env NODE_JQ_SKIP_INSTALL_BINARY=true","test:watch":"dotenv -- vitest","format:check":"prettier --check .","mcp-cli:build":"dotenv -- npx fastmcp dev dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"coderberry","email":"coderberry@gmail.com"},"_npmVersion":"10.9.2","description":"MCP server for querying JSON files using jq processor","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.25.0","which":"^5.0.0","fastmcp":"^3.12.0","node-jq":"^6.0.1","genson-js":"^0.0.8"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.3.4","tsx":"^4.19.2","vitest":"^3.2.4","cross-env":"^10.0.0","dotenv-cli":"^9.0.0","typescript":"^5.7.2","@types/node":"^22.10.2","@types/which":"^3.0.4"},"_npmOperationalInternal":{"tmp":"tmp/mcp-query-json-file_1.0.2_1753818537805_0.9695939559758076","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@berrydev-ai/mcp-query-json-file","version":"1.0.3","description":"MCP server for querying JSON files using jq processor","main":"dist/index.js","type":"module","bin":{"mcp-query-json-file":"dist/index.js"},"scripts":{"build":"tsc && shx chmod +x dist/*.js","clean":"rm -rf dist","dev":"dotenv -- tsx src/index.ts --json-file-path=tests/fixtures/sample.json --log-file-path=mcp-query-json-file.log","test":"dotenv -- vitest run","test:watch":"dotenv -- vitest","lint":"eslint . --ext .ts,.js --cache","lint:fix":"eslint . --ext .ts,.js --fix --cache","format":"prettier --write .","format:check":"prettier --check .","typecheck":"tsc --noEmit","cli":"npx @wong2/mcp-cli -c ./claude_desktop_config.json","mcp-cli:build":"dotenv -- npx fastmcp dev dist/index.js","preinstall":"cross-env NODE_JQ_SKIP_INSTALL_BINARY=true","prepublishOnly":"npm run build"},"keywords":["mcp","json","jq","query"],"author":{"name":"Eric Berry","url":"eric@berrydev.ai"},"license":"MIT","dependencies":{"fastmcp":"^3.12.0","genson-js":"^0.0.8","node-jq":"^6.0.1","which":"^5.0.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^22.10.2","@types/which":"^3.0.4","cross-env":"^10.0.0","dotenv-cli":"^9.0.0","shx":"^0.3.4","tsx":"^4.19.2","typescript":"^5.7.2","vitest":"^3.2.4"},"_id":"@berrydev-ai/mcp-query-json-file@1.0.3","gitHead":"50f724a729752d533d72c830e5986c6ea379185a","types":"./dist/index.d.ts","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-udnnRm6YbDED6fZFt5vUlUH2XS/mXOMNuRkyeP1KzmRgu02EaLXRuVv3clSSCK9u5F5es67SNkQLjpXTsdfuag==","shasum":"e1cee4c04e7183279fc1067b8b39cf928410be1b","tarball":"https://registry.npmjs.org/@berrydev-ai/mcp-query-json-file/-/mcp-query-json-file-1.0.3.tgz","fileCount":18,"unpackedSize":36197,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC12B9pEn4+4lSF+KBY57ILhfc1Yh9jn8yAa/74KYOVRQIgcBbhPgLNBPS21ObNMO8H7AVzy6BRrsdGrAxd4D5oxW4="}]},"_npmUser":{"name":"coderberry","email":"coderberry@gmail.com"},"directories":{},"maintainers":[{"name":"coderberry","email":"coderberry@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-query-json-file_1.0.3_1753820431202_0.5003900550362879"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-29T15:57:27.511Z","modified":"2025-07-29T20:20:31.647Z","1.0.0":"2025-07-29T15:57:27.797Z","1.0.1":"2025-07-29T18:30:11.439Z","1.0.2":"2025-07-29T19:48:57.988Z","1.0.3":"2025-07-29T20:20:31.406Z"},"author":{"name":"Eric Berry","url":"eric@berrydev.ai"},"license":"MIT","keywords":["mcp","json","jq","query"],"description":"MCP server for querying JSON files using jq processor","maintainers":[{"name":"coderberry","email":"coderberry@gmail.com"}],"readme":"# MCP Query JSON File\n\nAn 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.\n\n## Features\n\n- **JSON Querying**: Execute jq queries on JSON files with structured responses\n- **Schema Generation**: Generate JSON schemas from existing JSON files\n- **Audit Logging**: Complete audit trail of all query executions\n- **Size Validation**: Configurable limits to prevent oversized responses\n- **Cross-Platform**: Works on Windows, Linux, and macOS\n\n## Installation\n\n```bash\nnpm install -g @berrydev-ai/mcp-query-json-file\n```\n\n## Configuration\n\nThe server requires the following environment variables:\n\n| Variable         | Required | Default       | Description                    |\n| ---------------- | -------- | ------------- | ------------------------------ |\n| `JSON_FILE_PATH` | Yes      | -             | Path to the JSON file to query |\n| `JQ_PATH`        | Yes      | -             | Path to the jq executable      |\n| `MAX_DATA_SIZE`  | No       | `1000000`     | Maximum result size in bytes   |\n| `LOG_FILE_PATH`  | No       | `./query.log` | Path to the audit log file     |\n\n## Claude Desktop Setup\n\nAdd the following configuration to your Claude Desktop `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-query-json-file\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@berrydev-ai/mcp-query-json-file\"],\n      \"env\": {\n        \"JSON_FILE_PATH\": \"/path/to/your/data.json\",\n        \"JQ_PATH\": \"/opt/homebrew/bin/jq\",\n        \"MAX_DATA_SIZE\": \"1000000\",\n        \"LOG_FILE_PATH\": \"/var/logs/mcp-query-json-file.log\"\n      }\n    }\n  }\n}\n```\n\n## Usage Examples\n\n### Basic Queries\n\n**Get all users:**\n\n```\nqueryJson with query: \".users\"\n```\n\n**Filter active users:**\n\n```\nqueryJson with query: \".users[] | select(.active == true)\"\n```\n\n**Get user names only:**\n\n```\nqueryJson with query: \".users[].name\"\n```\n\n**Count total users:**\n\n```\nqueryJson with query: \".users | length\"\n```\n\n### Advanced Queries\n\n**Group users by status:**\n\n```\nqueryJson with query: \"group_by(.active) | map({active: .[0].active, count: length})\"\n```\n\n**Sort users by age:**\n\n```\nqueryJson with query: \".users | sort_by(.age)\"\n```\n\n### Schema Generation\n\nGenerate a JSON schema from your data:\n\n```\ngenerateSchema\n```\n\n### Query Statistics\n\nView query execution history:\n\n```\ngetQueryStats with limit: 20\n```\n\n## Tools\n\n### queryJson\n\nExecute a jq query on the configured JSON file.\n\n**Parameters:**\n\n- `query` (string): The jq query to execute\n\n**Response:**\n\n```json\n{\n  \"query\": \".users[0]\",\n  \"resultSize\": 156,\n  \"result\": {\n    \"id\": 1,\n    \"name\": \"John Doe\",\n    \"age\": 30\n  }\n}\n```\n\nIf the result exceeds the size limit:\n\n```json\n{\n  \"query\": \".users\",\n  \"resultSize\": 2500000,\n  \"warning\": \"Query result too large: 2500000 bytes exceeds limit of 1000000 bytes. Please refine your query to return less data.\",\n  \"result\": null\n}\n```\n\n### generateSchema\n\nGenerate a JSON schema from the configured JSON file.\n\n**Response:**\n\n```json\n{\n  \"filePath\": \"/path/to/data.json\",\n  \"schema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"users\": {\n        \"type\": \"array\",\n        \"items\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"id\": { \"type\": \"number\" },\n            \"name\": { \"type\": \"string\" }\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n### getQueryStats\n\nGet statistics about query execution history.\n\n**Parameters:**\n\n- `limit` (number, optional): Maximum number of recent queries to return (default: 10)\n\n**Response:**\n\n```json\n{\n  \"totalQueries\": 25,\n  \"successfulQueries\": 23,\n  \"failedQueries\": 2,\n  \"recentQueries\": [\n    {\n      \"timestamp\": \"2024-01-01T12:00:00Z\",\n      \"query\": \".users[0]\",\n      \"filePath\": \"/path/to/data.json\",\n      \"resultSize\": 156,\n      \"success\": true\n    }\n  ]\n}\n```\n\n## Resources\n\n### queryLog\n\nRead-only access to the complete audit trail of all query executions.\n\n**URI:** `queryLog`\n**Content-Type:** `application/json`\n\n## Development\n\n### Prerequisites\n\n- Node.js 18+\n- jq command-line tool\n- pnpm (recommended)\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd mcp-query-json-file\n\n# Install dependencies\npnpm install\n\n# Run tests\npnpm test\n\n# Start development server\npnpm dev\n```\n\n### Testing\n\nThe project includes comprehensive tests for:\n\n- Configuration validation\n- Query engine functionality\n- Audit logging\n- Error handling\n- Cross-platform compatibility\n\n```bash\n# Run all tests\npnpm test\n\n# Run tests in watch mode\npnpm test --watch\n```\n\n## Troubleshooting\n\n### jq Command Not Found\n\nIf you get \"jq command not found\" errors:\n\n1. **Install jq:**\n   - macOS: `brew install jq`\n   - Ubuntu/Debian: `sudo apt-get install jq`\n   - Windows: Download from https://stedolan.github.io/jq/\n\n2. **Or specify custom path:**\n   ```json\n   \"env\": {\n     \"JQ_PATH\": \"/usr/local/bin/jq\",\n     \"JSON_FILE_PATH\": \"/path/to/data.json\"\n   }\n   ```\n\n### Large Result Sets\n\nIf queries return \"too large\" warnings:\n\n1. **Increase the limit:**\n\n   ```json\n   \"env\": {\n     \"MAX_DATA_SIZE\": \"5000000\"\n   }\n   ```\n\n2. **Or refine your queries:**\n   - Use `limit(n)` to restrict results: `.users | limit(10)`\n   - Select specific fields: `.users[] | {name, age}`\n   - Add filters: `.users[] | select(.active == true)`\n\n### File Permissions\n\nEnsure the process has read access to your JSON file and write access to the log directory.\n\n## Local Test\n\n```bash\nnode ./dist/index.js \\\n  --json-file-path=./tests/fixtures/sample.json \\\n  --jq-path=/opt/homebrew/bin/jq \\\n  --max-data-size=1000000 \\\n  --log-file-path=./mcp-query-json-file.log\n```\n\n\n## License\n\nMIT\n","readmeFilename":"README.md"}