# Diff Anything MCP

Use the installed Diff Anything command line from an MCP client to compare local files, folders, and API schemas. The optional npm package runs over stdio as a child process of your client.

## Requirements and setup

- Node.js 22 or newer on macOS or Windows.
- An installed Diff Anything app with its command line. Install the app from [the product page](https://martingruner.com/projects/diffanything). On Windows, the Microsoft Store version provides the command line through its `diff-anything.exe` app execution alias. On a Mac, the Mac App Store version is sandboxed and cannot read files named on a command line, so install the free [Diff Anything command-line helper](https://martingruner.com/diff-anything-command-line.html), which installs `/usr/local/bin/diff-anything`.
- Folder and API schema comparisons require Diff Anything Pro. The CLI checks the app's locally cached entitlement; open the desktop app to purchase or restore Pro. The Free CLI permits plain-text and JSON comparisons, subject to its daily and file-size limits.
- `check_api_compatibility` requires a CLI whose help includes `--fail-on breaking`. Discovery checks the installed binary; an older app returns `update_required` for this tool.

Your MCP client starts the server with `npx`, which downloads the pinned version on first use; nothing else needs installing. In Claude Code:

```sh
claude mcp add diff-anything -e DIFF_ANYTHING_ROOTS='["/Users/you/Comparisons"]' -- npx -y @grunersoftware/diff-anything-mcp@0.1.0
```

In clients configured with JSON, the server entry is:

```json
{
  "mcpServers": {
    "diff-anything": {
      "command": "npx",
      "args": ["-y", "@grunersoftware/diff-anything-mcp@0.1.0"],
      "env": { "DIFF_ANYTHING_ROOTS": "[\"/Users/you/Comparisons\"]" }
    }
  }
}
```

To run without fetching from npm at startup, install a pinned version globally and use the `diff-anything-mcp` command instead:

```sh
npm install --global @grunersoftware/diff-anything-mcp@0.1.0
```

Set `DIFF_ANYTHING_ROOTS` in your client's server configuration to a JSON array of existing absolute directories that the server may compare. Until this is configured, only discovery works. Start with a dedicated directory containing files you intend to share with your client.

macOS discovery checks the command-line helper at `/usr/local/bin/diff-anything`, then `/Applications/Diff Anything.app/Contents/MacOS/diff-anything`, the same bundle in `~/Applications`, and absolute entries on `PATH`. A Mac App Store copy of the app is skipped, because its own executable cannot read the files; without the helper, tools return `helper_required` with the helper's download page. Windows discovery checks `%LOCALAPPDATA%\Microsoft\WindowsApps\diff-anything.exe` and `PATH`. The Microsoft Store package declares that app execution alias; enable it in Windows settings if it is disabled. For a direct install or another location, set `DIFF_ANYTHING_CLI` to the absolute executable path. Never use a shell command or arguments in that variable.

### VS Code

For a workspace configuration, create `.vscode/mcp.json`:

```json
{
  "servers": {
    "diff-anything": {
      "type": "stdio",
      "command": "diff-anything-mcp",
      "env": {
        "DIFF_ANYTHING_ROOTS": "[\"/Users/you/Comparisons\"]"
      }
    }
  }
}
```

If your client cannot find the global command, use the absolute path to Node as `command` and the absolute path to the installed package's `src/index.mjs` as the single entry in `args`. This also avoids Windows clients that cannot directly launch npm's `.cmd` shim. `npm root --global` identifies the global package directory.

### Clients using `mcpServers`

For a client such as Claude Code that accepts a project `.mcp.json`, use the same server entry under `mcpServers`. This Windows example launches Node directly:

```json
{
  "mcpServers": {
    "diff-anything": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\@grunersoftware\\diff-anything-mcp\\src\\index.mjs"],
      "env": {
        "DIFF_ANYTHING_ROOTS": "[\"C:\\\\Users\\\\you\\\\Comparisons\"]"
      }
    }
  }
}
```

Replace example paths with your actual installation and comparison directories. Restart or reload the server in your client, then call `discover_capabilities` first. Setup references: [VS Code MCP configuration](https://code.visualstudio.com/docs/agent-customization/mcp-servers) and [MCP SDK host setup](https://ts.sdk.modelcontextprotocol.io/v2/get-started/real-host.html).

## Tools

| Tool | Input | Result |
| --- | --- | --- |
| `discover_capabilities` | `{}` | Installed CLI version, flag support, configured roots and wrapper limits. It does not probe Pro ownership. |
| `compare_files` | Absolute `left` and `right` paths | The CLI's auto-detected comparison report. |
| `compare_folders` | Absolute `left` and `right` directory paths | The CLI's default folder comparison report (Pro). |
| `check_api_compatibility` | Absolute `left` and `right` schema paths | API comparison with `--fail-on breaking` (Pro and a supporting CLI). |

Example input:

```json
{"left":"/Users/you/Comparisons/before.json","right":"/Users/you/Comparisons/after.json"}
```

Exit 1 is a completed comparison result, not a server failure. For file and folder comparisons it sets `countedDifferences`; for API checks it makes `compatibilityCheckPassed` false. Review the CLI report and its warnings: a failed compatibility check can mean a breaking or unclassified change. A comparison is not proof that a backup is complete or an API is compatible in every respect.

The wrapper returns the CLI report without rewriting its values or removing its masking. There are no tool arguments for raw CLI flags, disabling masking, overriding Pro, merging, batch manifests or writing report files. Errors use `isError` with a code such as `missing_app`, `helper_required`, `pro_required`, `update_required`, `outside_roots`, `timeout` or `output_limit` and the CLI's explanation where available.

## Local processing and permissions

Diff Anything performs its comparisons locally and sends none of your data to an AI model. The npm wrapper has no hosted runtime, account, API key, HTTP listener or required network connection at runtime. Installing packages requires registry access; launching the installed package directly avoids an npm fetch at startup.

**Your MCP client controls what happens to returned tool output.** Comparison results can include filenames, paths, document content and changed values. A client may send that output to its model provider or store it. Configure that client's data handling and tool approvals before comparing sensitive files. Existing CLI masking is not a universal secret scanner.

Tools leave compared files unchanged. The CLI can update its local free-comparison usage ledger and read its cached Pro entitlement. The server inherits your process permissions and environment. Allowed roots validate resolved input paths, including symlinks. Folder inputs are scanned before comparison and reject nested symbolic links, junctions and special files, because the CLI can follow links. This validation is capped at 100,000 entries and 60 seconds per tree. These are application-level guards, not an OS sandbox or protection against another process changing files during a comparison. Use local, stable directories; network mounts or cloud placeholders may perform I/O through the operating system.

Each CLI invocation has a 60-second timeout and a combined stdout/stderr limit of 1 MiB. Output beyond the limit is discarded and the process is stopped; a partial report is never presented as complete. One tool request runs at a time; overlapping requests return `busy`. Client cancellation stops the active CLI child. Large comparisons should be narrowed into smaller pairs.

## Development

```sh
npm ci
npm test
npm pack
```

Tests exercise the actual MCP stdio transport with a fixture CLI, argument validation, platform discovery paths, allowed roots, symlink escape rejection, Pro errors, cancellation and output limits. A real installed app is needed to verify platform packaging and entitlement behavior end to end.