# rubyhash-mcp

MCP server for [RubyHash](https://rubyhash.dev). Gives any MCP-capable agent (Claude Code, Claude Desktop, Cursor, and others) two deterministic Ruby tools:

- **ruby_hash_diff**: compare two Ruby hash literals, or paste raw failing Minitest/RSpec output, and get a structured report of exactly what changed: changed values with before and after, added and removed keys, and explicit type changes (nil to String, Integer to Float, symbol keys vs string keys).
- **ruby_to_json**: convert a Ruby hash or array literal (hashrockets, symbol keys, shorthand syntax, nesting, nil/true/false) to clean JSON with sorted keys.

Everything runs locally in the server process. Nothing is uploaded, logged, or stored, the same privacy promise as [rubyhash.dev](https://rubyhash.dev).

## Tools

- `ruby_hash_diff`: Compare two Ruby hash literals, or paste raw failing Minitest/RSpec output, and get a structured report: changed values with before and after, added and removed keys, and explicit type changes (nil to String, Integer to Float, symbol keys vs string keys).
- `ruby_to_json`: Convert a Ruby hash or array literal (hashrockets, symbol keys, shorthand syntax, nesting, nil/true/false) to clean JSON with alphabetically sorted keys.

## Why an agent would want this

When a Ruby test fails on two large nearly identical hashes, comparing them by reading is slow and error prone, for humans and for language models. A 40-key nested hash diff burns context and invites mistakes. This server does the comparison with a real recursive descent parser and hands back only the differences, deterministically.

## Install

```json
{
  "mcpServers": {
    "rubyhash": {
      "command": "npx",
      "args": ["-y", "rubyhash-mcp"]
    }
  }
}
```

Or for Claude Code:

```bash
claude mcp add rubyhash -- npx -y rubyhash-mcp
```

## Example

Input (raw test output):

```
-{"uid"=>"u@example.test", "role"=>"admin", "seats"=>3}
+{"uid"=>"u@example.test", "role"=>"editor", "seats"=>3.0}
```

Output:

```json
{
  "equal": false,
  "summary": "2 changed, 0 added, 0 removed, 1 type change",
  "changed": [
    { "path": "role", "before": "admin", "after": "editor", "typeChanged": false },
    { "path": "seats", "before": 3, "after": 3, "beforeType": "Integer", "afterType": "Float", "typeChanged": true }
  ]
}
```

## Also available as an HTTP API

If you cannot run a local MCP server, the same tools are exposed at the [RubyHash Agent API](https://rubyhash.dev/agents), with an OpenAPI description and an x402 machine-payable catalog.

## Development

```bash
npm install
npm test   # 36 unit tests
```

## License

MIT for this package. The rubyhash.dev site and its browser tool are separate, private, and all rights reserved.