{"_id":"@ai-toolbox-mcp/json-mcp-server","_rev":"2-5872f2454bae67e4a6da045d58daede2","name":"@ai-toolbox-mcp/json-mcp-server","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@ai-toolbox-mcp/json-mcp-server","version":"1.0.0","keywords":["mcp","json","jq","schema","validation","model-context-protocol"],"author":{"url":"eric@berrydev.ai","name":"Eric Berry"},"license":"MIT","_id":"@ai-toolbox-mcp/json-mcp-server@1.0.0","maintainers":[{"name":"coderberry","email":"coderberry@gmail.com"}],"homepage":"https://github.com/ai-toolbox-mcp/json-mcp-server#readme","bugs":{"url":"https://github.com/ai-toolbox-mcp/json-mcp-server/issues"},"bin":{"json-mcp-server":"index.js"},"dist":{"shasum":"7cade805c9202740ba2bdad46b9690c7d8474cda","tarball":"https://registry.npmjs.org/@ai-toolbox-mcp/json-mcp-server/-/json-mcp-server-1.0.0.tgz","fileCount":9,"integrity":"sha512-LI1mZqAddAyx3t2mnLcMqgotuEbQZcSml2CKwEOcHzUN4PeJUVbC7vNTBVgTYppJj1npZoBbsO+HNlrjy831UQ==","signatures":[{"sig":"MEUCIQDYHdP2uxXI4wS61droNt5iju9C7UFd3m4mur8V4zkzcAIgPDvexkdzIy0XEdDf+y7bch0iTaQaBZ1oiiZZrwyPPNE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":33313},"main":"index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"62b6c5612ad17fd2a6514b471e3e1977fe322074","scripts":{"dev":"node index.js --verbose=true","test":"node test.js","clean":"npm run clean-win || npm run clean-unix","start":"node index.js","release":"node scripts/release.js","clean-win":"if exist node_modules rmdir /s /q node_modules && if exist package-lock.json del package-lock.json","clean-unix":"rm -rf node_modules package-lock.json","publish:all":"npm run publish:npm && npm run publish:github","publish:npm":"npm publish --registry=https://registry.npmjs.org/","release:major":"node scripts/release.js major","release:minor":"node scripts/release.js minor","release:patch":"node scripts/release.js patch","publish:github":"npm publish --registry=https://npm.pkg.github.com"},"_npmUser":{"name":"coderberry","email":"coderberry@gmail.com"},"repository":{"url":"git+https://github.com/ai-toolbox-mcp/json-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server providing JSON querying, schema generation, and validation tools","directories":{},"_nodeVersion":"22.14.0","dependencies":{"ajv":"^8.17.1","which":"^4.0.0","node-jq":"^6.0.1","commander":"^12.1.0","genson-js":"^0.0.8","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/json-mcp-server_1.0.0_1753301517824_0.6978017621061243","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@ai-toolbox-mcp/json-mcp-server","version":"1.0.1","description":"MCP server providing JSON querying, schema generation, and validation tools","type":"module","main":"index.js","bin":{"json-mcp-server":"index.js"},"scripts":{"start":"node index.js","dev":"node index.js --verbose=true","test":"node test.js","clean-win":"if exist node_modules rmdir /s /q node_modules && if exist package-lock.json del package-lock.json","clean-unix":"rm -rf node_modules package-lock.json","clean":"npm run clean-win || npm run clean-unix","publish:github":"npm publish --registry=https://npm.pkg.github.com","publish:npm":"npm publish --registry=https://registry.npmjs.org/","publish:all":"npm run publish:npm && npm run publish:github","release:patch":"node scripts/release.js patch","release:minor":"node scripts/release.js minor","release:major":"node scripts/release.js major","release":"node scripts/release.js"},"publishConfig":{"registry":"https://registry.npmjs.org"},"keywords":["mcp","json","jq","schema","validation","model-context-protocol"],"author":{"name":"Eric Berry","url":"eric@berrydev.ai"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","node-jq":"^6.0.1","ajv":"^8.17.1","commander":"^12.1.0","genson-js":"^0.0.8","which":"^4.0.0"},"engines":{"node":">=18.0.0"},"repository":{"type":"git","url":"git+https://github.com/ai-toolbox-mcp/json-mcp-server.git"},"bugs":{"url":"https://github.com/ai-toolbox-mcp/json-mcp-server/issues"},"homepage":"https://github.com/ai-toolbox-mcp/json-mcp-server#readme","_id":"@ai-toolbox-mcp/json-mcp-server@1.0.1","gitHead":"4c7111124f02b2436d3f263434744519e0e19529","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-MW/flMYduvC5iL61kcMl79j2rJeOWIFX90RiWZUviyhLCLUJTwQTAb4BZ/BsEUsvYkgcAZL83wclNpzEFGgruA==","shasum":"b8316df1128d44c5a929fded206a5f10771b852f","tarball":"https://registry.npmjs.org/@ai-toolbox-mcp/json-mcp-server/-/json-mcp-server-1.0.1.tgz","fileCount":9,"unpackedSize":33315,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHQRgCjutdh7RBDtlONFD08/2TTmBdEwWh+oYcAiNTlvAiEA1/Sph99YTdE2KJlYdaRWVUlJIXoTKCp14JPaeyOsR1Y="}]},"_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/json-mcp-server_1.0.1_1753302558887_0.5681676712793333"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-23T20:11:57.741Z","modified":"2025-07-23T20:29:19.345Z","1.0.0":"2025-07-23T20:11:58.047Z","1.0.1":"2025-07-23T20:29:19.070Z"},"bugs":{"url":"https://github.com/ai-toolbox-mcp/json-mcp-server/issues"},"author":{"name":"Eric Berry","url":"eric@berrydev.ai"},"license":"MIT","homepage":"https://github.com/ai-toolbox-mcp/json-mcp-server#readme","keywords":["mcp","json","jq","schema","validation","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/ai-toolbox-mcp/json-mcp-server.git"},"description":"MCP server providing JSON querying, schema generation, and validation tools","maintainers":[{"name":"coderberry","email":"coderberry@gmail.com"}],"readme":"# JSON MCP Server\n\nA Model Context Protocol (MCP) server that provides powerful JSON manipulation tools using `node-jq` with a locally installed `jq` binary, native Node.js fs operations, and `genson-js`.\n\n## Prerequisites\n\n**🚨 Required: Install jq binary on your system**\n\n**Windows:**\n```powershell\n# Chocolatey (recommended)\nchoco install jq\n\n# Scoop\nscoop install jq\n\n# Manual download\n# Download jq.exe from https://stedolan.github.io/jq/download/\n# Place in PATH or use --jq-path parameter\n\n# WSL (if using Windows Subsystem for Linux)\nwsl -e sudo apt-get install jq\n```\n\n**macOS:**\n```bash\nbrew install jq\n```\n\n**Linux:**\n```bash\n# Ubuntu/Debian\nsudo apt-get install jq\n\n# CentOS/RHEL/Fedora\nsudo yum install jq  # or sudo dnf install jq\n\n# Arch Linux\nsudo pacman -S jq\n```\n\n**Verify installation:**\n```bash\n# Windows (Command Prompt or PowerShell)\njq --version\n\n# Unix/Linux/macOS\njq --version\n# Should output something like: jq-1.6\n```\n\n## Features\n\n- **Query JSON**: Use jq notation to query JSON files with complex filters and transformations\n- **Generate JSON Schema**: Automatically generate JSON schemas from existing JSON data\n- **Validate JSON Schema**: Ensure that JSON schemas are properly formed and valid\n\n## Installation\n\n1. Clone or create the project directory:\n```bash\nmkdir json-mcp-server\ncd json-mcp-server\n```\n\n2. Save the provided files (`index.js`, `package.json`) in this directory\n\n3. Clean install dependencies:\n```bash\n# Clean any existing installations first\nnpm run clean  # or manually: rm -rf node_modules package-lock.json\nnpm install\n```\n\n4. Make the script executable (Unix/Linux/macOS):\n```bash\nchmod +x index.js\n```\n\n## Claude Desktop Installation\n\n**Mac/Linux**:\n\n```json\n{\n  \"mcpServers\": {\n    \"json-mcp-server\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/index.js\",\n        \"--verbose=true\",\n        \"--file-path=/path/to/file.json\",\n        \"--jq-path=/path/to/jq\"\n      ]\n    }\n  }\n}\n```\n\n**Windows**:\n\n```json\n{\n  \"mcpServers\": {\n    \"json-mcp-server\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"C:\\\\path\\\\to\\\\index.js\",\n        \"--verbose=true\",\n        \"--file-path=C:\\\\path\\\\to\\\\file.json\",\n        \"--jq-path=C:\\\\path\\\\to\\\\jq.exe\"\n      ]\n    }\n  }\n}\n```\n\n## Usage\n\n### Command Line Arguments\n\n- `--verbose=true`: Enable verbose logging (default: false)\n- `--file-path=/path/to/file.json`: Set a default file path for operations (optional)\n- `--jq-path=/path/to/jq`: Specify custom jq binary path (auto-detected if not provided)\n\n### Starting the Server\n\n**Windows (Command Prompt):**\n```cmd\nREM Basic usage (auto-detects jq)\nnode index.js\n\nREM With verbose logging\nnode index.js --verbose=true\n\nREM With default file path (use forward slashes or escape backslashes)\nnode index.js --verbose=true --file-path=C:/Users/username/data.json\n\nREM With custom jq binary path\nnode index.js --verbose=true --jq-path=\"C:\\Program Files\\jq\\jq.exe\"\n```\n\n**Windows (PowerShell):**\n```powershell\n# Basic usage\nnode index.js\n\n# With verbose logging\nnode index.js --verbose=true\n\n# With default file path\nnode index.js --verbose=true --file-path=\"C:\\Users\\username\\data.json\"\n\n# With custom jq binary path\nnode index.js --verbose=true --jq-path=\"C:\\Program Files\\jq\\jq.exe\"\n```\n\n**Unix/Linux/macOS:**\n```bash\n# Basic usage (auto-detects jq)\nnode index.js\n\n# With verbose logging\nnode index.js --verbose=true\n\n# With default file path\nnode index.js --verbose=true --file-path=/home/user/data.json\n\n# With custom jq binary path\nnode index.js --verbose=true --jq-path=/usr/local/bin/jq\n```\n\n**Using npm scripts (all platforms):**\n```bash\nnpm start\nnpm run dev  # with verbose logging\n```\n\n## Tools\n\n### 1. query_json\n\nQuery JSON data using jq notation.\n\n**Parameters:**\n- `filePath` (string, optional if default set): Absolute path to JSON file\n- `query` (string, required): jq query expression\n\n**Example queries:**\n- `\".\"` - Return entire JSON\n- `\".users\"` - Get users array\n- `\".users[0].name\"` - Get first user's name\n- `\".users[] | select(.active == true)\"` - Filter active users\n- `\".[].price | add\"` - Sum all prices\n\n### 2. generate_json_schema\n\nGenerate a JSON schema from a JSON file using genson-js.\n\n**Parameters:**\n- `filePath` (string, optional if default set): Absolute path to JSON file\n\n**Output:** Complete JSON schema that describes the structure of your data.\n\n### 3. validate_json_schema\n\nValidate that a JSON schema is properly formed.\n\n**Parameters:**\n- `schema` (object): JSON schema object to validate, OR\n- `schemaFilePath` (string): Path to file containing JSON schema\n\n**Output:** Validation result with detailed feedback.\n\n## Example JSON Data\n\nCreate a test file `test-data.json`:\n\n```json\n{\n  \"users\": [\n    {\n      \"id\": 1,\n      \"name\": \"John Doe\",\n      \"email\": \"john@example.com\",\n      \"active\": true,\n      \"roles\": [\"user\", \"admin\"]\n    },\n    {\n      \"id\": 2,\n      \"name\": \"Jane Smith\",\n      \"email\": \"jane@example.com\",\n      \"active\": false,\n      \"roles\": [\"user\"]\n    }\n  ],\n  \"metadata\": {\n    \"version\": \"1.0\",\n    \"created_at\": \"2024-01-01T00:00:00Z\"\n  }\n}\n```\n\n## Example Usage with MCP Client\n\nOnce connected to an MCP client, you can use the tools like this:\n\n### Query Examples\n```javascript\n// Get all active users\nquery_json({\n  filePath: \"/absolute/path/to/test-data.json\",\n  query: \".users[] | select(.active == true)\"\n})\n\n// Get user emails\nquery_json({\n  filePath: \"/absolute/path/to/test-data.json\",\n  query: \".users[].email\"\n})\n\n// Count total users\nquery_json({\n  filePath: \"/absolute/path/to/test-data.json\",\n  query: \".users | length\"\n})\n```\n\n### Schema Generation\n```javascript\ngenerate_json_schema({\n  filePath: \"/absolute/path/to/test-data.json\"\n})\n```\n\n### Schema Validation\n```javascript\nvalidate_json_schema({\n  schema: {\n    \"type\": \"object\",\n    \"properties\": {\n      \"name\": {\"type\": \"string\"}\n    },\n    \"required\": [\"name\"]\n  }\n})\n```\n\n## Error Handling\n\nThe server provides detailed error messages for:\n- Invalid file paths\n- Malformed jq queries\n- Invalid JSON data\n- Schema validation errors\n- File access issues\n\n## Requirements\n\n- Node.js >= 18.0.0\n- Access to the file system for reading JSON files\n- Files must use absolute paths for security\n\n## Dependencies\n\n- `@modelcontextprotocol/sdk`: MCP protocol implementation (latest v1.x)\n- `node-jq`: Node.js wrapper for jq binary (uses your local jq installation)\n- `genson-js`: JSON schema generation\n- `ajv`: JSON schema validation\n- `commander`: Command line argument parsing\n- `which`: Binary path detection utility\n\n## Troubleshooting\n\n### jq Binary Issues\n\nIf you get \"jq binary not found\" errors:\n\n**Windows:**\n1. **Install jq**: Follow the prerequisites section above\n2. **Check PATH**: Ensure jq is in your system PATH\n   ```cmd\n   where jq\n   REM Should show path like: C:\\ProgramData\\chocolatey\\bin\\jq.exe\n   ```\n3. **Try jq.exe**: Some Windows installations use `jq.exe`\n   ```cmd\n   jq.exe --version\n   ```\n4. **Custom path**: Use `--jq-path` if jq is in a non-standard location\n   ```cmd\n   node index.js --jq-path=\"C:\\tools\\jq\\jq.exe\"\n   ```\n\n**Unix/Linux/macOS:**\n1. **Install jq**: Follow the prerequisites section above\n2. **Check PATH**: Ensure jq is in your system PATH\n   ```bash\n   which jq  # Should show path like /usr/local/bin/jq\n   ```\n3. **Custom path**: Use `--jq-path` if jq is in a non-standard location\n   ```bash\n   node index.js --jq-path=/custom/path/to/jq\n   ```\n\n### Dependency Issues\n\nIf you encounter dependency issues:\n\n1. **Clean install**:\n   ```bash\n   npm run clean\n   npm install\n   ```\n\n2. **Node version**: Ensure you're using Node.js >= 18.0.0\n   ```bash\n   node --version\n   ```\n\n3. **Clear npm cache**:\n   ```bash\n   npm cache clean --force\n   ```\n\n### Permission Issues\n\n**Windows:**\n- Usually no permission changes needed\n- If you get access denied errors, run Command Prompt or PowerShell as Administrator\n- Ensure jq.exe is not blocked by antivirus software\n\n**Unix/Linux/macOS:**\nIf you get permission errors:\n```bash\nchmod +x index.js\n# And ensure jq binary is executable\nchmod +x $(which jq)\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n","readmeFilename":"README.md"}