UpgradeLens

Evidence-backed dependency upgrade intelligence for AI coding agents.

Anonymous free evaluation quota — no signup and no API key required. Read-only. npm and PyPI only.

Release status: v0.4.1 is deployed on the public Worker with every v0.3.1 route and tool retained. The official MCP Registry serves v0.4.1 through a signed-tag GitHub OIDC release; Bazaar indexing remains pending.

One deterministic, source-cited call answers: should this dependency move from version A to version B, and what must be handled?

Remote MCP: https://upgradelens.mattpicone.workers.dev/mcp (streamable HTTP)
REST: /openapi.json · /llms.txt · /pricing.json
Decisions: proceed | review_required | block | unknown — unknown rather than fabricated certainty
Action gate: edit dependency files only when action_allowed is true; target discovery always requires a follow-up check
Sources: deps.dev, OSV.dev, registry.npmjs.org, pypi.org, endoflife.date. Every semantic claim carries evidence with a source URL and fetch timestamp.

Install

GitHub dependency pull requests

name: UpgradeLens dependency review
on:
  pull_request:
    types: [opened, synchronize, reopened]
permissions:
  contents: read
  id-token: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: mattpicone/upgradelens-action@v0
        with:
          max-spend-usd: "0.03"

The UpgradeLens Action handles Dependabot, Renovate, and ordinary dependency PRs. It receives one repository-bound free review per rolling 30 days through GitHub OIDC, uploads no repository source, and can automatically pay for additional $0.01 reviews when a compatible wallet secret is configured.

Cursor

Add UpgradeLens to Cursor (official cursor.com/install-mcp installer; also works as cursor://anysphere.cursor-deeplink/mcp/install?name=upgradelens&config=eyJ1cmwiOiJodHRwczovL3VwZ3JhZGVsZW5zLm1hdHRwaWNvbmUud29ya2Vycy5kZXYvbWNwIn0=).

Or add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "upgradelens": {
      "url": "https://upgradelens.mattpicone.workers.dev/mcp"
    }
  }
}

A checked-in example is at examples/cursor/.cursor/mcp.json. This is a docs/config install, not a Cursor Marketplace listing.

Claude Code

claude mcp add --transport http upgradelens https://upgradelens.mattpicone.workers.dev/mcp

Codex CLI

codex mcp add upgradelens --url https://upgradelens.mattpicone.workers.dev/mcp

Or configure it directly:

# ~/.codex/config.toml
[mcp_servers.upgradelens]
url = "https://upgradelens.mattpicone.workers.dev/mcp"

The CLI install path was verified end-to-end on 2026-08-30 with Codex 0.150.0-alpha.8: enabled connection, tool discovery, and a real check_dependency_upgrade call. The verification used an environment-backed owner Bearer token so it could not count as business demand; public evaluation installs need no token.

Gemini CLI

This repository includes gemini-extension.json and GEMINI.md:

gemini extensions install https://github.com/mattpicone/upgradelens

The Gemini extension gallery indexes public repos that have the gemini-cli-extension GitHub topic. That topic is set on this repository; gallery listing is a separate crawl and is not claimed here.

GitHub Copilot Agent Plugins

copilot plugin install mattpicone/upgradelens

Portable Agent Plugins 1.0 plugin.json plus Copilot's root .mcp.json are checked in and point at the remote HTTPS server. The existing mcp.json remains for other Agent Plugins-compatible clients. No credential is embedded. Maintainer-directory indexing is separate from these files.

Microsoft APM

apm install --mcp io.github.mattpicone/upgradelens --transport http

PydanticAI

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

server = MCPServerStreamableHTTP("https://upgradelens.mattpicone.workers.dev/mcp")
agent = Agent("your-model", toolsets=[server])

LangChain / LangGraph

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "upgradelens": {
        "transport": "streamable_http",
        "url": "https://upgradelens.mattpicone.workers.dev/mcp",
    }
})
tools = await client.get_tools()

Plain REST

curl -X POST https://upgradelens.mattpicone.workers.dev/v1/upgrade/review \
  -H 'content-type: application/json' \
  -d '{
    "ecosystem": "npm",
    "package": "express",
    "current_version": "4.19.2",
    "target_version": "5.1.0",
    "runtime": {"node": "22"},
    "detail": "compact"
  }'

One anonymous evaluation unit is shared across MCP and REST for a rolling 30-day network identity. When paid mode is enabled, additional units use x402 v2 USDC at $0.01 per analysis (10,000 atomic USDC); the public endpoint stays fail-closed in validation until the external testnet acceptance gate is recorded. POST /v1/keys is intentionally retired.

MCP tools

Tool	Use when	Do not use when
`review_dependency_upgrade`	Preferred: review an exact Dependabot, Renovate, npm, or PyPI version change and return one compact decision plus cited migration actions	The target or current version is unknown, or the task is outside npm/PyPI
`check_dependency_upgrade`	You are about to change a package from a known current version to a known target version and need verified compatibility/vulnerability/EOL/breaking-change evidence before editing dependency files	Merely installing a package or searching docs
`find_safe_upgrade_target`	A dependency should be upgraded but the target version is not yet known — returns ranked candidates that must each be checked	The target version is already chosen, or as authorization to edit dependency files
`plan_dependency_upgrade`	A target is selected and you need ordered, source-cited migration actions	General tutorials

Response (abbreviated):

{
  "next_action": "review_migration_plan",
  "billing": {
    "mode": "validation",
    "units": 1,
    "price_usd": 0.01,
    "trial_remaining": null,
    "network": null,
    "payment_status": "validation_free"
  },
  "decision": "review_required",
  "action_allowed": false,
  "risk_score": 37,
  "latest_stable": "5.2.1",
  "security_delta": {
    "advisories_fixed_by_target": [{"id": "GHSA-qw6h-vgh9-j6wx", "aliases": ["CVE-2024-43796"]}]
  },
  "compatibility": {
    "runtime_supported": true,
    "dependency_changes": {"added": ["router"], "removed": ["depd"], "changed": []}
  },
  "reasons": ["Major version jump (4.19.2 -> 5.1.0).", "Upgrade fixes 1 known advisory: GHSA-qw6h-vgh9-j6wx."],
  "coverage": {"registry": {"status": "complete"}, "osv": {"status": "complete"}},
  "evidence": [{"id": "ev_...", "source_type": "osv", "source_url": "https://osv.dev/vulnerability/GHSA-qw6h-vgh9-j6wx", "fetched_at": "..."}],
  "confidence": 0.95,
  "freshness": "..."
}

Why call this instead of doing it yourself?

An agent can combine deps.dev + OSV + registries + changelogs manually — this service exists to compress those 5–7 fetch/normalize/reconcile steps into one deterministic call with:

security delta (advisories affecting current vs. fixed by / still affecting target — including "this target is itself affected, pick a newer one"),
runtime compatibility (engines.node / requires_python evaluated against your runtime),
direct dependency diff between the two versions,
yanked/deprecated/EOL flags,
documented breaking changes (deterministically extracted from official release notes, with URLs),
provenance for every claim, cacheable and repeatable.

Architecture

Cloudflare Worker (TypeScript/Hono) + D1 (SQLite). Version-pair analyses are cached by (ecosystem, package, from, to, runtime, analysis_version). Breaking-change facts are precomputed by a scheduled GitHub Actions job using deterministic extraction from official release notes — no LLM calls at runtime, ever. See docs/OPERATIONS.md.

API stability

Versioned under /v1. Response schemas only gain fields; existing fields are not repurposed. analysis_version identifies scoring-logic revisions.

License

MIT — see LICENSE. Security policy: SECURITY.md.