# JSON MCP Server

A powerful MCP (Model Context Protocol) server for editing and managing JSON files with dot-notation path access.

## Features

- ✅ Read JSON values using dot-separated paths
- ✏️ Set or update JSON values (supports nested structures)
- 🗑️ Delete JSON key-value pairs
- 🔄 Auto-create missing JSON files
- 🌳 Automatically create intermediate nested objects

## Installation

```bash
# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

## Running the Server

```bash
python mcp_json.py
```

The server runs on stdio transport by default, which is the standard for MCP clients like Claude Desktop.

## Tools

### 1. `json:get` - Get Value

Retrieve a value from a JSON file using a dot-separated key path.

**Parameters:**
- `path`: JSON file path (absolute or relative)
- `key`: Dot-separated key path (e.g., `"user.name"`)

**Examples:**
```
json:get(path="data.json", key="name")
json:get(path="config.json", key="database.host")
json:get(path="users.json", key="users.0.name")
```

### 2. `json:set` - Set Value

Set or update a value in a JSON file. Supports JSON strings or plain strings. Automatically creates missing intermediate objects.

**Parameters:**
- `path`: JSON file path
- `key`: Dot-separated key path
- `value`: Value to set (can be JSON string)

**Examples:**
```
json:set(path="data.json", key="name", value="John Doe")
json:set(path="config.json", key="port", value="3000")
json:set(path="config.json", key="database", value='{"host":"localhost","port":5432}')
json:set(path="data.json", key="tags", value='["python","mcp","json"]')
json:set(path="config.json", key="api.endpoints.users", value="/api/v1/users")
```

### 3. `json:delete` - Delete Key

Delete a key from a JSON file using a dot-separated key path.

**Parameters:**
- `path`: JSON file path
- `key`: Dot-separated key path

**Examples:**
```
json:delete(path="data.json", key="oldField")
json:delete(path="config.json", key="database.password")
json:delete(path="user.json", key="settings.theme")
```

## Usage Examples

### Example 1: Create User Configuration

```
json:set(path="user.json", key="profile.name", value="John Doe")
json:set(path="user.json", key="profile.email", value="john@example.com")
json:set(path="user.json", key="profile.age", value="30")
json:set(path="user.json", key="settings.theme", value="dark")
json:set(path="user.json", key="settings.notifications", value="true")
json:get(path="user.json", key="profile")
```

**Result `user.json`:**
```json
{
  "profile": {
    "name": "John Doe",
    "email": "john@example.com",
    "age": "30"
  },
  "settings": {
    "theme": "dark",
    "notifications": "true"
  }
}
```

### Example 2: Manage API Configuration

```
json:set(path="api.json", key="api.baseUrl", value="https://api.example.com")
json:set(path="api.json", key="api.version", value="v2")
json:set(path="api.json", key="api.timeout", value="5000")
json:set(path="api.json", key="endpoints", value='{"users":"/users","posts":"/posts"}')
json:get(path="api.json", key="api")
json:delete(path="api.json", key="endpoints.posts")
```

### Example 3: Working with Arrays

```
json:set(path="tasks.json", key="tasks", value='[{"id":1,"title":"Learn MCP","done":false}]')
json:get(path="tasks.json", key="tasks.0.title")
```

## MCP Client Configuration

Add this server to your MCP client (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "json-editor": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_json.py"],
      "enabled": true
    }
  }
}
```

Or using the virtual environment Python:

```json
{
  "mcpServers": {
    "json-editor": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/mcp_json.py"],
      "enabled": true
    }
  }
}
```

## How It Works

- **Dot-notation paths**: Use dots (`.`) to separate nested keys: `"user.profile.name"`
- **Auto-creation**: Missing files are created as empty objects `{}`
- **Nested objects**: Missing intermediate objects are automatically created
- **Value parsing**: The `value` parameter attempts JSON parsing first, falls back to string
- **Pretty formatting**: JSON files are saved with 2-space indentation

## Error Messages

- `❌ Key not found: {key}` - When trying to get or delete a non-existent key
- `Invalid JSON format: {path}` - When the file exists but contains invalid JSON

## Development

The server uses FastMCP, which provides:
- Automatic parameter validation
- Built-in error handling
- Support for multiple transports (stdio, SSE, HTTP)

## License

MIT