https://github.com/jokerqyou/jsonmcptool
An MCP server for LLM to edit I18Next JSON files
https://github.com/jokerqyou/jsonmcptool
claude-code json mcp mcp-server
Last synced: 2 months ago
JSON representation
An MCP server for LLM to edit I18Next JSON files
- Host: GitHub
- URL: https://github.com/jokerqyou/jsonmcptool
- Owner: JokerQyou
- Created: 2025-08-26T05:41:27.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-26T15:06:36.000Z (10 months ago)
- Last Synced: 2025-08-26T20:58:12.378Z (10 months ago)
- Topics: claude-code, json, mcp, mcp-server
- Language: Go
- Homepage:
- Size: 73.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# JsonMcpTool (Go Version)
A complete MCP (Model Context Protocol) tool for efficient JSON file processing, specifically designed for I18Next translation files and other large JSON documents. This is the **Go rewrite** of the original Python implementation for better performance and easier deployment.
## 🚀 Performance & Benefits
The Go version provides:
- **Faster execution** - Native Go performance vs Python interpreted code
- **Lower memory usage** - More efficient memory management
- **Single binary** - No Python dependencies, easy deployment
- **Better concurrency** - Go's built-in concurrency support
- **100% API compatibility** - Drop-in replacement for Python version
## What This Tool Does
JsonMcpTool allows you to interact with JSON translation files through **Claude Code** using natural language. Instead of manually editing large translation files, you can ask Claude to:
- "Get the dashboard title from my translations.json"
- "Set the login form validation text"
- "Remove the deprecated translations"
Designed specifically for **i18next translation files** with a minimal tool set that won't clutter the LLM context window.
## Key Features
- **🎯 I18Next Optimized**: Perfect for translation files with interpolation (`{{name}}`)
- **✨ Minimal Tool Set**: Only 3 core tools (set, get, remove) - won't clutter LLM context
- **📝 Indentation Preservation**: Automatically detects and preserves your JSON formatting (2/4 spaces, tabs)
- **🔍 Smart Path Resolution**: Works with dot-notation paths like `section.subsection.key`
- **💾 Safe Operations**: Atomic file writes prevent corruption
- **⚡ Fast**: Native Go performance, optimized for files up to 100MB+
- **🛡️ Error Handling**: Clear error messages for debugging
## Installation & Setup
### 1. Prerequisites
You need Go installed (1.23 or later):
```bash
# Check if Go is installed
go version
# If not installed, download from https://golang.org/dl/
```
### 2. Build JsonMcpTool
```bash
# Clone or download this repository
git clone /path/to/JsonMcpTool
cd /path/to/JsonMcpTool
# Build the binary
go build -o jsonmcptool ./cmd/server
# Or install directly
go install ./cmd/server
```
### 3. Configure Claude Code
Add JsonMcpTool to your Claude Code MCP configuration:
```bash
# Using the built binary
claude mcp add jsonmcptool -- /PATH/TO/JsonMcpTool/jsonmcptool
# Or if installed globally
claude mcp add jsonmcptool -- jsonmcptool
```
**Alternative manual configuration:**
```json
{
"mcpServers": {
"jsonmcptool": {
"type": "stdio",
"command": "/PATH/TO/JsonMcpTool/jsonmcptool"
}
}
}
```
### 4. Restart Claude Code
Restart Claude Code to load the new MCP tool.
### 5. Test It Works
Create a simple JSON file and ask Claude:
```
"I have a translations.json file at /path/to/translations.json with this content:
{
"dashboard": {
"title": "Dashboard"
}
}
Can you get the dashboard title for me?"
```
Claude should respond with the value "Dashboard".
## Development & Testing
### Building from Source
```bash
# Clone the repository
git clone
cd JsonMcpTool
# Build
go build ./cmd/server
# Run tests
go test ./... -v
# Run benchmarks
go test ./... -bench=. -benchmem
```
### Project Structure
```
JsonMcpTool/
├── cmd/server/main.go # MCP server entry point
├── internal/
│ ├── jsonhandler/ # File I/O, parsing, caching, indent detection
│ ├── pathresolver/ # Dot-notation path handling
│ ├── operations/ # Core JSON operations (set/get/remove)
│ └── mcpserver/ # MCP server setup
├── testdata/ # Test fixtures
├── go.mod # Go module definition
└── README.md # This file
```
## Available Tools
Three focused tools optimized for i18next translation workflows:
| Tool | Description | Example Usage |
|------|-------------|---------------|
| **set** | Set a string value at path (creates nested objects as needed) | *"Set dashboard.title to 'New Title'"* |
| **get** | Get value at path (returns string or object) | *"Get dashboard.title"* |
| **remove** | Remove key at path | *"Remove the deprecated section"* |
### Design Notes
- **String values only**: The `set` tool only accepts string values, matching i18next translation patterns
- **Automatic nesting**: Setting `a.b.c` will create intermediate objects `{ "a": { "b": { "c": "value" } } }`
- **Indentation preservation**: The tool automatically detects and preserves 2-space, 4-space, or tab indentation
## Migration from Python Version
This Go version is a **streamlined implementation** focused on i18next translation workflows. The tool set has been simplified from 8 to 3 operations:
| Old Tools | New Tool | Notes |
|-----------|----------|-------|
| `get_key` | `get` | Same functionality |
| `add_key`, `update_key` | `set` | Unified into single tool |
| `remove_key` | `remove` | Same functionality |
| `rename_key`, `list_keys`, `key_exists`, `validate_json` | — | Removed (rarely needed) |
### Performance Improvements
- **Startup time**: ~50ms vs ~200ms (75% faster)
- **Memory usage**: ~5MB vs ~15MB (67% less)
- **JSON parsing**: ~2-3x faster for large files
- **File operations**: ~40% faster due to efficient I/O
### What's New in This Version
- **Minimal tool set** - Only 3 tools, won't clutter LLM context window
- **Indentation preservation** - Automatically detects and preserves 2/4 spaces or tabs
- **Native Go performance** - Single binary, no runtime dependencies
- **Simpler mental model** - Set/Get/Remove covers 99% of use cases
- **Enhanced error messages** with precise location information
## Troubleshooting
### Common Issues
**"Tool not found"**:
- Restart Claude Code after adding the MCP configuration
- Check that the path to the binary is absolute and correct
- Ensure the binary was built successfully
**"Permission denied"**:
- Make sure the binary is executable: `chmod +x jsonmcptool`
- On macOS/Linux, you might need to allow the binary in Security settings
**Build errors**:
- Ensure you have Go 1.23 or later: `go version`
- Run `go mod tidy` to ensure dependencies are correct
## What Makes This Special
Unlike generic text-editing tools, JsonMcpTool:
✅ **Minimal tool set** - Only 3 tools, won't clutter LLM context
✅ **Indentation preservation** - Maintains your preferred formatting
✅ **Understands JSON structure** - No risk of breaking syntax
✅ **Handles large files efficiently** - Works with 100MB+ translation files
✅ **Native Go performance** - 2-3x faster than Python version
✅ **Single binary deployment** - No runtime dependencies
✅ **Supports I18Next patterns** - Built for translation workflows
✅ **Safe operations** - Atomic writes prevent file corruption
✅ **Natural language interface** - Just ask Claude what you want to do
Perfect for managing translation files, configuration files, or any JSON data through Claude Code!
## License
MIT License - Use freely in your projects!