# MCP JSON Navigator

A Model Context Protocol (MCP) server that provides intelligent JSON navigation and search capabilities for AI assistants.
Mostly design for saving tokens and manipulating large files > 10MB in a few seconds.

Require [FileSystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem).
*Note the json should note use "." in keys*


> Capabilities
> 1. "Search keys & values ("phone", "email", "location")"
> 2. "Precise path lookup with optional case-sensitive matching"
> 3. "Structural exploration of very large JSON files
> (without loading everything into model context)"

--- 
## 📦 Installation

MacOS/Linux
```shell
git clone https://github.com/Adsdworld/mcp-json-navigator && cd mcp-json-navigator && npm install && npm run build
```
Windows (tested)
```bash
git clone https://github.com/Adsdworld/mcp-json-navigator; cd mcp-json-navigator; npm install; npm run build
```

## ⚙️ Configuration

Add to your MCP settings file (e.g., `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "json-navigator": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_USERNAME\\mcp-json-navigator\\build\\index.js"]
    }
  }
}
```

Replace `YOUR_USERNAME` and the path with your actual installation location.
---

## 🔎 Json-query
```json
{ 
  "Request": {
    "limit": 50,
    "query": "phone",
    "filepath": "C:\\Shared\\With\\Claude\\data.json",
    "caseSensitive": false
  },
  "Response": {
  "results": [
    {
      "path": "result[0]",
      "score": 2
    },
    {
      "path": "result[1]",
      "score": 2
    }
  ]
}
}
```

## 🛤️ Json-explore

```json
{
  "Request": {
    "filepath": "C:\\Shared\\With\\Claude\\data.json",
    "jsonpath": "result[1]",
    "verbosity": 5
  },
  "Response": {
    "message": "Hello, Brannon! Your order number is: #100",
    "phoneNumber": "(268) 822-7569",
    "phoneVariation": "+90 343 871 10 66",
    "status": "disabled",
    "name": "{object: 3 keys, 49 chars}",
    "username": "Madalyn-Koss",
    "password": "_jRAnwKTcLZwdj6",
    "emails": "[list: 2 items, 54 chars]",
    "location": "{object: 6 keys, 175 chars}",
    "website": "https://sour-debris.com/",
    "domain": "wrong-leaf.org",
    "job": "{object: 5 keys, 123 chars}",
    "creditCard": "{object: 3 keys, 60 chars}",
    "uuid": "476c7b47-0c28-4dc1-b872-7c4256a95675",
    "objectId": "68fe628328b168737793b750"
  }
}
```

--- 


## 🎯 Who is this for?

**This tool is designed for AI assistants that need to navigate and search through large JSON files efficiently.**

When dealing with massive JSON structures (hundreds of MB, deeply nested objects, thousands of entries), AI models face several challenges:
- **Token limitations**: Large JSON files can't fit entirely in the context window
- **Performance**: Parsing and searching large structures is slow
- **Precision**: Finding specific data in complex nested structures is difficult

**MCP JSON Navigator solves these problems by:**
- Providing intelligent exploration with adjustable verbosity levels
- Using fuzzy search with camelCase tokenization for natural queries
- Allowing precise navigation using JSON paths
- Grouping and scoring results intelligently

## ✨ Features

### 1. **Smart JSON Exploration** (`json-explore`)
Navigate through JSON structures with adjustable detail levels:

```typescript
// Get an overview (verbosity: 0-1)
{ "users": "list", "config": "object", "version": "string" }

// See structure with counts (verbosity: 2-3)
{ "users": "[list: 150 items]", "config": "{object: 12 keys, 450 chars}" }

// Full expansion for small objects (verbosity: 4-5)
{ "users": [...], "config": {...} }
```

**Parameters:**
- `filepath`: Path to the JSON file
- `jsonpath` (optional): Navigate to specific path (e.g., `users[0].profile`)
- `verbosity`: 0-5 (default: 4)
    - `0`: Keys only
    - `1`: Keys with types
    - `2`: Keys with counts
    - `3`: Keys with counts and character sizes
    - `4`: Smart expansion for small objects
    - `5`: Raw data
- `listDisplayLimit`: Max items to show in arrays (default: 5)
- `objectDisplayLimit`: Max keys to show in objects (default: 6)
- `charDisplayLimit`: Max characters for expansion (default: 200)

### 2. **Intelligent Search** (`json-query`)
Search through keys and values with fuzzy matching and camelCase tokenization:

```typescript
// These all find "phoneNumber" and "phoneVariation"
query: "phone"     ✓
query: "number"    ✓
query: "variation" ✓
```

**How it works:**
1. **Tokenization**: Splits camelCase, snake_case, kebab-case, and generates n-grams
2. **Fuzzy Matching**: Uses similarity scoring to find partial matches
3. **Weighted Scoring**: Keys score higher than values
4. **Smart Grouping**: Groups related results from the same JSON branch

**Parameters:**
- `filepath`: Path to the JSON file
- `query`: Search term (supports partial matches)
- `limit`: Max results to return (default: 20, min: 10)
- `caseSensitive`: Enable exact matching filter (default: false)

When `caseSensitive: true`, returns an additional `exactMatch` field with results that contain the exact query string.


## 🚀 Usage Examples

### Example 1: Exploring a Large JSON File

```typescript
// First, get an overview
json-explore({
  filepath: "C:\\Shared\\With\\Claude\\data.json",
  verbosity: 1
})
// → { "users": "list", "products": "list", "config": "object" }

// Then navigate to a specific section
json-explore({
  filepath: "C:\\Shared\\With\\Claude\\data.json",
  jsonpath: "users[0]",
  verbosity: 5
})
// → Full details of the first user
```

### Example 2: Searching for Contacts

```typescript
// Find all phone-related fields by high scores paths
json-query({
  filepath: "C:\\Shared\\With\\Claude\\contacts.json",
  query: "phone",
  limit: 20
})
// → Results with paths like "contacts[0].phoneNumber", "contacts[1].phoneVariation"

// Returning a list of exact paths found that exactly match + high scores paths
json-query({
  filepath: "C:\\Shared\\With\\Claude\\contacts.json",
  query: "qsbHBJ5sd4HBSDsdjhHBS",
  caseSensitive: true
})
```

### Example 3: Complex Navigation

```typescript
// Navigate deep into nested structures
json-explore({
  filepath: "api-response.json",
  jsonpath: "result.data.items[3].metadata",
  verbosity: 3
})
// → Full details metadata either an object / list / primitif
```

## 🛠️ Technical Details

### Architecture

- **TypeScript-based**: Fully typed for reliability
- **MCP Protocol**: Built on Model Context Protocol standard
- **Fast Fuzzy Search**: Uses `fast-fuzzy` library for efficient matching
- **Inverted Index**: Builds searchable index with n-gram tokenization
- **Smart Grouping**: Groups results by JSON structure for better relevance

### Search Algorithm

1. **Tokenization**:
    - Normalizes text (camelCase → camel Case)
    - Generates 3-5 character n-grams
    - Builds inverted index: token → [paths with weights]

2. **Query Phase**:
    - Tokenizes query
    - Computes fuzzy similarity scores
    - Accumulates scores per path
    - Applies key/value weights

3. **Result Grouping**:
    - Groups paths by structural similarity
    - Scores by frequency × depth
    - Returns top representative paths

## 📄 License

MIT License - See [LICENSE](LICENSE) file for details.

**You are free to:**
- ✓ Use commercially
- ✓ Modify
- ✓ Distribute
- ✓ Use privately

**Just mention the source:** https://github.com/Adsdworld/mcp-json-navigator

## 🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## 📚 Related Projects

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP Servers](https://github.com/modelcontextprotocol/servers)

## 🔗 Links

- **GitHub**: https://github.com/Adsdworld/mcp-json-navigator
- **MCP Documentation**: https://modelcontextprotocol.io/

---

Built with ❤️ for AI assistants navigating complex JSON structures.