# JSON Editor MCP

A Model Context Protocol (MCP) server for editing JSON files with read, write, and deep merge capabilities. Perfect for managing multilingual Next.js projects and other JSON-based configurations.

> **Note:** This is an actively developed tool. Feature requests and bug reports are welcome! File issues on [GitHub](https://github.com/peternagy1332/json-editor-mcp/issues).

## Problems This Solves

- 💰 **Significant token savings**: Edit specific JSON paths instead of reading/writing entire files
- ⚡ **Efficient operations**: ~100 tokens per edit vs 4,000+ tokens for full file operations
- 📦 **Handles large files**: Large translation files may not fit into context windows; targeted operations work regardless of file size
- 🚀 **Faster edits**: Avoids slow network round-trips from reading/writing entire files
- 🔑 **Prevents duplicate keys**: AI can't see full translation JSON and creates duplicates; targeted operations avoid this issue
- 🔍 **Targeted reads**: Read only the values you need using dot notation paths
- ✏️ **Targeted writes**: Update only specific paths, automatically creates missing nested structures
- 🗑️ **Targeted deletes**: Remove specific paths from JSON files
- 🔀 **Deep merge support**: Merge duplicate keys with recursive object merging
- 📚 **Multi-file operations**: Read, write, or delete the same path from multiple JSON files efficiently
- 📘 **TypeScript support**: Full type definitions included
- 🤖 **MCP compliant**: Works with AI assistants (Cursor, Claude, ChatGPT) and development tools

## Installation

```bash
bun add json-editor-mcp
```

## Usage

### MCP Server Configuration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "json-editor": {
      "command": "bunx",
      "args": ["json-editor-mcp"]
    }
  }
}
```

### Cursor Rules Integration

Copy the rule file to your project to ensure AI assistants use MCP tools:

```bash
cp .cursor/rules/json-editor-mcp.mdc /path/to/your/project/.cursor/rules/
```

## Tools

### `read_multiple_json_values`

Reads the same dot notation path from one or more JSON files in a single operation. Returns a map with file paths as keys and the extracted values as values. Useful for comparing translations across language files or reading from a single file.

**Note:** For single file operations, pass an array with one file path: `["messages/en.json"]`

**Input JSON files:**

**messages/en.json:**
```json
{
  "common": {
    "welcome": "Welcome"
  }
}
```

**messages/es.json:**
```json
{
  "common": {
    "welcome": "Bienvenido"
  }
}
```

**Tool call:**
```
read_multiple_json_values(["messages/en.json", "messages/es.json"], "common.welcome")
```

**Output:**
```json
{
  "messages/en.json": "Welcome",
  "messages/es.json": "Bienvenido"
}
```

**Single file example:**
```
read_multiple_json_values(["messages/en.json"], "common.welcome")
```

**Output:**
```json
{
  "messages/en.json": "Welcome"
}
```

### `write_json_values`

Writes a value to a JSON file at a specified dot notation path. Automatically creates missing nested paths and preserves existing structure.

**Input JSON (messages/en.json):**
```json
{
  "common": {
    "welcome": "Welcome"
  }
}
```

**Tool call:**
```
write_json_values("/absolute/path/to/messages/en.json", "pages.about.title", "About Us")
```

**Output JSON (messages/en.json):**
```json
{
  "common": {
    "welcome": "Welcome"
  },
  "pages": {
    "about": {
      "title": "About Us"
    }
  }
}
```

**Output:**
```
Successfully wrote to /absolute/path/to/messages/en.json
```

### `delete_multiple_json_values`

Deletes a value at a specified dot notation path from one or more JSON files. Returns a map with file paths as keys and deletion results as values.

**Note:** For single file operations, pass an array with one file path: `["messages/en.json"]`

**Input JSON files:**

**messages/en.json:**
```json
{
  "common": {
    "welcome": "Welcome",
    "goodbye": "Goodbye"
  }
}
```

**messages/es.json:**
```json
{
  "common": {
    "welcome": "Bienvenido",
    "goodbye": "Adiós"
  }
}
```

**Tool call:**
```
delete_multiple_json_values(["messages/en.json", "messages/es.json"], "common.goodbye")
```

**Output:**
```json
{
  "messages/en.json": "Successfully deleted",
  "messages/es.json": "Successfully deleted"
}
```

**Output JSON files:**

**messages/en.json:**
```json
{
  "common": {
    "welcome": "Welcome"
  }
}
```

**messages/es.json:**
```json
{
  "common": {
    "welcome": "Bienvenido"
  }
}
```

### `merge_duplicate_keys`

Performs a deep merge of duplicate keys in a JSON file. Primitives use last-value-wins, objects merge recursively, and arrays use last-value-wins. Useful when AI assistants create duplicate keys because they can't see the full file structure.

**Input JSON (messages/en.json):**
```json
{
  "common": {
    "welcome": "Welcome"
  },
  "common": {
    "goodbye": "Goodbye"
  }
}
```

**Tool call:**
```
merge_duplicate_keys("messages/en.json")
```

**Output JSON (messages/en.json):**
```json
{
  "common": {
    "welcome": "Welcome",
    "goodbye": "Goodbye"
  }
}
```

## API Reference

**Path Notation:** Dot notation for nested paths (e.g., `"common.welcome"`, `"pages.home.title"`)

**Error Handling:**
- File not found: Creates empty object `{}` for reads
- Invalid JSON: Returns error message
- Path not found: Error for reads, auto-creates for writes

**Deep Merge:** Primitives last-value-wins, objects merge recursively, arrays last-value-wins

## Development

```bash
git clone https://github.com/peternagy1332/json-editor-mcp.git
cd json-editor-mcp
bun install
bun run build
```

## License

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

## Support

File issues on [GitHub](https://github.com/peternagy1332/json-editor-mcp/issues).