# rn-upgrade-helper-mcp

An MCP server for React Native Upgrade Helper diffs.

It fetches the same generated template diffs used by React Native Upgrade Helper, backed by `react-native-community/rn-diff-purge`, and exposes them as MCP tools that agents can call directly.

## Tools

- `get_upgrade_helper_url`: builds the web Upgrade Helper URL.
- `list_changed_files`: returns structured changed-file metadata.
- `get_file_diff`: returns the diff for one file.
- `get_upgrade_diff`: returns the full diff, optionally filtered by `android`, `ios`, or `js`.
- `summarize_upgrade`: summarizes changed areas and notable files.

## Local Development

```sh
npm install
npm run build
node dist/index.js
```

## Codex Plugin Usage

This repo can also be installed as a Codex plugin because it contains:

- `.codex-plugin/plugin.json`
- `.mcp.json`
- a bundled `dist/index.js`

Build before committing/publishing:

```sh
npm install
npm run build
```

Then push the repo to GitHub. Users can install the plugin from the GitHub repo in Codex.

## Client Integrations

This repo includes ready-to-copy MCP config snippets for:

- OpenAI Codex
- Codex plugin wrapper
- Cursor
- Claude Desktop
- Claude Code
- Windsurf / Cascade
- Cline
- VS Code / GitHub Copilot Agent Mode

See [`docs/CLIENTS.md`](docs/CLIENTS.md).

## Direct MCP Client Config

After publishing to npm:

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

For local testing from this repo:

```json
{
  "mcpServers": {
    "rn-upgrade-helper": {
      "command": "node",
      "args": ["/absolute/path/to/rn-upgrade-helper-mcp/dist/index.js"]
    }
  }
}
```

## Example Inputs

Example upgrade request:

```json
{
  "from": "0.73.9",
  "to": "0.79.2",
  "appName": "MyApp",
  "packageName": "com.example.myapp"
}
```

## Publishing

```sh
npm install
npm run build
npm publish --access public
```

If publishing under an internal scope, rename the package first:

```json
{
  "name": "@your-scope/rn-upgrade-helper-mcp"
}
```

Then update the MCP client config to use the scoped package name.

## Notes

- The server requires Node 18.18+ because it uses native `fetch`.
- Diffs are fetched from:
  - `https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<from>..<to>.diff`
  - fallback: `https://github.com/react-native-community/rn-diff-purge/compare/release/<from>..release/<to>.diff`
- Package name and app name are applied by replacing `com.rndiffapp`, `com/rndiffapp`, and `RnDiffApp` in the generated template diff.