# Ripedeps

> Ripedeps plans dependency upgrades for the package.json of a Node.js project: the newest versions that are old enough, within the step size you allow and aligned with each other (peer dependencies and the first-level dependencies of the packages), with a decision and one explanation sentence per package. Deterministic code and live npm registry data, no AI at runtime. It only suggests: it never writes to your machine or repository.

How it decides: the candidate combinations are **ranked** in a fixed order (fewest peer violations, then fewest misaligned dependencies, then the least lag behind the newest version; alignment beats freshness), every package gets a **decision** (`status`: `upgrade`, `held`, `current`, `outside-focus` or `skipped`, with the chosen version and `bestVersion`), and every decision comes with an **explanation** (an `explanation` sentence and structured `reasons[]`). The ranking itself is not a response field. Details: https://ripedeps.com/how-it-works

The main way for an AI agent to use it is the MCP server below. The same planner is also available as a REST API and a bash script.

## Use it over MCP

- Endpoint: https://mcp.ripedeps.com/mcp
- Transport: MCP Streamable HTTP, stateless, no login. Only POST is supported (GET and DELETE answer 405).
- One tool: `plan_upgrade`, marked `readOnlyHint`.

Claude Code:

```bash
claude mcp add --transport http ripedeps https://mcp.ripedeps.com/mcp
```

`.mcp.json` (Claude Code, project scope):

```json
{
  "mcpServers": {
    "ripedeps": {
      "type": "http",
      "url": "https://mcp.ripedeps.com/mcp"
    }
  }
}
```

`.cursor/mcp.json` (Cursor):

```json
{
  "mcpServers": {
    "ripedeps": {
      "url": "https://mcp.ripedeps.com/mcp"
    }
  }
}
```

`.vscode/mcp.json` (VS Code):

```json
{
  "servers": {
    "ripedeps": {
      "type": "http",
      "url": "https://mcp.ripedeps.com/mcp"
    }
  }
}
```

Any other client that supports remote MCP servers over Streamable HTTP only needs the URL.

## The plan_upgrade tool

Send exactly one of `packageJson` and `packageJsonUrl`. Recommended: `minAgeDays: 7`.

- `packageJson` (string; default: one of the two): The full text of package.json. Formatting is preserved in the diff. Up to 256 KB.
- `packageJsonUrl` (string (https URL); default: one of the two): The raw URL of a package.json. The service downloads it. See URL input below.
- `focus` (string[]; default: empty (everything)): Exact names or * globs. A bare name like trpc also matches @trpc/*. Up to 50 entries.
- `minAgeDays` (integer 0–365; default: 0, or the file’s ripedeps entry): Minimum age of a version since its release. 7 is a good start.
- `maxBump` (patch | minor | major; default: minor, or the file’s ripedeps entry): The highest allowed step, measured from the version in your file.
- `skipAdoptConfig` (boolean; default: false): true: do not write the effective settings into the output as a ripedeps entry.

## What the tool returns

- `structuredContent`: the full plan as JSON (`diff`, `updatedPackageJson`, `packages`, `warnings`, `notes`, `meta`). Its schema: https://ripedeps.com/schema/PlanResponse.schema.json
- A text summary with one line per upgraded, held or skipped package and its explanation, then `Note:` and `Warning:` lines. At most 50 package lines; the rest is only in `structuredContent.packages[].explanation`.
- The diff as text, ready for `patch -p1`.

Real text summary for a file with next and react (7-day gate, minor steps):

```text
Ripedeps plan: 1 to upgrade, 2 held back, 0 current.
next ^15.0.0 -> ^15.5.28: `next` 15.0.0 -> 15.5.28 (minor step, 9 days old, age gate 7); newest version that qualifies; not taken: `next@16.4.3` is a major step from 15.0.0, above the allowed minor level
`react` held at 18.3.1; not taken: `react@19.3.1` is a major step from 18.3.1, above the allowed minor level
`react-dom` held at 18.3.1; not taken: `react-dom@19.3.1` is a major step from 18.3.1, above the allowed minor level
Note: The `ripedeps` entry was added (minAgeDays 7, maxBump minor) so later runs use the same limits
```

## How an agent should use it

Ripedeps decides which versions, the agent does the work, the user reviews. Suggested rules for CLAUDE.md or AGENTS.md:

```text
## Dependency upgrades

- Use the ripedeps MCP tool `plan_upgrade` to decide versions; do not pick versions yourself.
- Pass the file text as `packageJson` with `minAgeDays: 7`. Keep `maxBump` at `minor` unless I ask for a major upgrade.
- Apply the returned diff (`patch -p1`), then run `npm install` and the test suite.
- Report the `explanation` of every upgraded or held package and any `Note:` and `Warning:` lines. Do not commit unless I ask.
```

- A focused request ("upgrade only axios") is a `focus` entry, not a full upgrade. A bare name like `trpc` also matches `@trpc/*`.
- A monorepo needs one call per package.json.
- A major upgrade needs `maxBump: "major"`, usually together with `focus`.
- Without `skipAdoptConfig: true` the output file gets a `ripedeps` entry with the settings used; a `Note:` line says so.

## Limits and errors

- Up to 256 KB per file, 300 dependencies, 50 focus entries; about 30 requests per minute.
- A plan that takes longer than 60 seconds ends as an error result (`plan_timeout`). Call the tool again: the package data loaded so far is cached.
- Errors are returned as an error result with `<code>: <message>`. Codes:

- `invalid_json` (400): The request body is not valid JSON.
- `invalid_request` (400): Unknown or invalid parameters, or the wrong content type.
- `invalid_package_json` (400): The package.json text is not valid JSON.
- `invalid_ripedeps_config` (400): The ripedeps entry in the file has an invalid value. The message names the key.
- `invalid_input_url` (400): Bad packageJsonUrl, or both or neither of packageJson and packageJsonUrl were sent.
- `too_many_focus_entries` (400): More than 50 focus entries.
- `payload_too_large` (413): The file is larger than 256 KB.
- `too_many_dependencies` (413): More than 300 dependencies.
- `no_processable_dependency` (422): Nothing in the file can be planned (every entry is skipped).
- `input_url_blocked` (422): The URL, or a redirect target, points to an address that is not allowed.
- `input_fetch_failed` (422): The URL could not be downloaded: DNS, timeout, connection or a non-2xx answer.
- `input_not_package_json` (422): The downloaded file is HTML, or not a JSON object. Use the raw file URL.
- `not_found` (404): Unknown path.
- `method_not_allowed` (405): Wrong method for a known path. The Allow header lists the right one.
- `rate_limited` (429): Too many requests. Slow down and retry.
- `registry_unreachable` (502): The npm registry could not be reached and there is no cached data.
- `plan_timeout` (504): The plan did not finish in time. Retry: what was loaded stays cached.
- `unhealthy` (503): Returned by /healthz when the database is not reachable.
- `internal_error` (500): Unexpected error.

## Privacy

Uploaded package.json files and the resulting recommendations are stored for analysis and for improving the algorithm. Do not send files that contain secrets. Tell the user this before sending their file. Details: https://ripedeps.com/privacy

## Docs

- [MCP](https://ripedeps.com/mcp): the MCP server: client setup, the tool, use cases and prompts
- [API](https://ripedeps.com/api): the REST API (POST https://api.ripedeps.com/plan): parameters, response, errors, JSON Schemas
- [CLI](https://ripedeps.com/cli): the bash script, https://ripedeps.com/ripedeps.sh
- [How it works](https://ripedeps.com/how-it-works): the algorithm in plain terms
- [Privacy](https://ripedeps.com/privacy): what is stored and how to have it deleted
- [Tool](https://ripedeps.com/tool): the web tool