json-explorer-mcp 1.0.0 → 1.0.1

package/README.md

@@ -8,13 +8,19 @@ An MCP (Model Context Protocol) server for efficiently exploring large JSON file
 - **Smart truncation** - Large values are automatically summarized
 - **Caching** - Parsed JSON is cached with file modification checks
 - **Schema inference** - Understand structure without reading all data
+- **Schema validation** - Validate data against JSON Schema
 - **Aggregate statistics** - Get counts, distributions, and numeric stats
 
 ## Installation
 
 ```bash
-npm install
-npm run build
+npm install -g json-explorer-mcp
+```
+
+Or use directly with npx:
+
+```bash
+npx json-explorer-mcp
 ```
 
 ## Usage
@@ -27,8 +33,8 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
 {
   "mcpServers": {
     "json-explorer": {
-      "command": "node",
-      "args": ["/path/to/json-explorer-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "json-explorer-mcp"]
     }
   }
 }
@@ -42,8 +48,8 @@ Add to `.mcp.json` in your project:
 {
   "mcpServers": {
     "json-explorer": {
-      "command": "node",
-      "args": ["dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "json-explorer-mcp"]
     }
   }
 }
@@ -55,11 +61,12 @@ Add to `.mcp.json` in your project:
 
 Get an overview of a JSON file including size, structure type, and a depth-limited preview.
 
-```
+```typescript
 json_inspect(file: "/path/to/data.json")
 ```
 
 Returns:
+
 ```json
 {
   "file": "/path/to/data.json",
@@ -77,18 +84,19 @@ Returns:
 
 List all keys (for objects) or indices (for arrays) at a given path with type info and previews.
 
-```
+```typescript
 json_keys(file: "/path/to/data.json", path: "$.users")
 ```
 
 Returns:
+
 ```json
 {
   "path": "$.users",
   "type": "array",
   "keys": [
-    { "key": "[0]", "type": "object", "preview": "{\"id\": 1, \"name\": \"Alice\", ...}", "path": "$.users[0]" },
-    { "key": "[1]", "type": "object", "preview": "{\"id\": 2, \"name\": \"Bob\", ...}", "path": "$.users[1]" }
+    { "key": "[0]", "type": "object", "preview": "{\"id\": 1, ...}", "path": "$.users[0]" },
+    { "key": "[1]", "type": "object", "preview": "{\"id\": 2, ...}", "path": "$.users[1]" }
   ],
   "totalCount": 1000
 }
@@ -98,7 +106,7 @@ Returns:
 
 Retrieve the value at a specific path. Large values are automatically truncated.
 
-```
+```typescript
 json_get(file: "/path/to/data.json", path: "$.users[0]")
 ```
 
@@ -106,11 +114,12 @@ json_get(file: "/path/to/data.json", path: "$.users[0]")
 
 Infer the JSON schema/structure at a path. For arrays, samples items to determine the item schema.
 
-```
+```typescript
 json_schema(file: "/path/to/data.json", path: "$.users")
 ```
 
 Returns:
+
 ```json
 {
   "path": "$.users",
@@ -128,11 +137,45 @@ Returns:
 }
 ```
 
+### json_validate
+
+Validate JSON data against a JSON Schema. Schema can be provided inline or as a path to a schema file.
+
+```typescript
+json_validate(
+  file: "/path/to/data.json",
+  schema: { "type": "object", "properties": { "id": { "type": "integer" } }, "required": ["id"] },
+  path: "$.users[0]"
+)
+```
+
+Or with a schema file:
+
+```typescript
+json_validate(
+  file: "/path/to/data.json",
+  schema: "/path/to/schema.json"
+)
+```
+
+Returns:
+
+```json
+{
+  "valid": false,
+  "errorCount": 2,
+  "errors": [
+    { "path": "/id", "message": "must be integer", "keyword": "type", "params": {} },
+    { "path": "", "message": "must have required property 'name'", "keyword": "required", "params": {} }
+  ]
+}
+```
+
 ### json_search
 
 Search for keys or values matching a pattern (regex supported).
 
-```
+```typescript
 json_search(file: "/path/to/data.json", query: "email", searchType: "key")
 json_search(file: "/path/to/data.json", query: "@example.com", searchType: "value")
 ```
@@ -141,7 +184,7 @@ json_search(file: "/path/to/data.json", query: "@example.com", searchType: "valu
 
 Get sample items from an array. Supports first, last, random, or range-based sampling.
 
-```
+```typescript
 json_sample(file: "/path/to/data.json", path: "$.users", count: 5, mode: "random")
 ```
 
@@ -149,16 +192,14 @@ json_sample(file: "/path/to/data.json", path: "$.users", count: 5, mode: "random
 
 Get aggregate statistics for array fields. If no path provided, discovers and analyzes all arrays of objects in the file.
 
-```
+```typescript
 json_stats(file: "/path/to/data.json")
 ```
 
 Returns:
+
 ```json
 {
-  "arrays": [
-    { "path": "$.users", "length": 1000, "itemType": "object", "fields": ["id", "name", "status"], "fieldCount": 10 }
-  ],
   "stats": [
     {
       "path": "$.users",
@@ -173,7 +214,8 @@ Returns:
 ```
 
 With a specific path:
-```
+
+```typescript
 json_stats(file: "/path/to/data.json", path: "$.users", fields: ["status", "created_at"])
 ```
 
@@ -197,6 +239,9 @@ npm install
 # Build
 npm run build
 
+# Run tests
+npm test
+
 # Run in development mode
 npm run dev
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-explorer-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for efficiently exploring large JSON files",
   "type": "module",
   "main": "dist/index.js",